Belgian Amiga Club - ADF Collection/BS1 part 05.zip/BS1 part 5/Empty.adf/SuperBaseDBL.doc

Text File | 1992-02-07 | 228KB | 8,250 lines

            SUPERBASE PROFESSIONAL
             DATABASE MANAGEMENT LANGUAGE
                 USER GUIDE

BEFORE YOU BEGIN...

This Volume presents you with two user guides,one for Superbase's Database
Management Language (DML) and one for the Forms Editor. Although they are
both under the same cover, they can be treated as separate manuals. Each
has its own Contents, Index, chapter numbers and page numbers.

Note that the Forms Editor is a separate program from Superbase
Professional. You will find instructions on how to install and load it on
your computer in the Readme document which is supplied on the demonstration
file disk. If you haven't done so already, you should read this document
now. It also provides details of any features of Superbase Professional
that are not covered in either Volume 1 or 2.

                i

DML USER GUIDE
CONTENTS

CHAPTER 1
INTRODUCTION TO DML                        1-1
Using this guide                        1-1
CHAPTER 2
OVERVIEW                            2-1
Operating Modes                            2-1
Keywords and Reserved Words                    2-1
Commands and Statements                        2-2
Variables                            2-2
File Types                            2-4
Fields                                2-5
Date and Time                            2-6
Functions                            2-6
Operators                            2-7
Constants                            2-13
Expressions                            2-14
Line Format and Labels                        2-14
Syntax                                2-15
CHAPTER 3
THE PROGRAM EDITOR                        3-1
Creating a New Program                        3-3
Editing a Program                        3-4
Using the Command Line                        3-6
Loading a Program                        3-7
Saving a Program                        3-7
Running a Program                        3-8
Creating a Start Up Program                    3-8
CHAPTER 4
FUNCTION KEYS                            4-1
Setting a Function Key                        4-1
Function Keys for Commands                    4-2
Functions Keys for Text and Program Entry            4-3

                ii

Editing a Function Key String                    4-4
Function Key Files                        4-5
CHAPTER 5
KEYWORD REFERENCE GUIDE                        5-1
Syntax Conventions                        5-1
? Commands                            5-3
?                                5-8
? DIRECTORY                            5-9
? LIST                                5-9
? MEMORY                            5-10
? QUERY                                5-10
? STATUS                            5-11
? TEXT                                5-12
ABS                                5-13
ADD                                5-14
AFTER GROUP                            5-17
AFTER REPORT                            5-18
ASC                                5-18
ASK                                5-19
ATN                                5-20
BEFORE GROUP                            5-21
BELL                                5-22
BLANK                                5-22
BREAK                                5-23
CALL                                5-24
CHAIN                                5-24
CHR$                                5-24
CLEAR                                5-26
CLOSE                                5-26
CLOSE FIELDS                            5-27
CLOSE FILE                            5-28
CLOSE FORM                            5-28
CLS                                5-29
COL                                5-29
COPY                                5-30
COS                                5-30
CREATE                                5-31
CREATE INDEX                            5-32
DATA                                5-33
DATE$                                5-34
DATEBASE                            5-35

                iii

DAY                                5-36
DAY$                                5-37
DAYS                                5-38
DELETE                                5-39
DIM                                5-39
DIRECTORY                            5-40
DISKSPACE                            5-41
EDIT                                5-42
EJECT                                5-43
END                                5-44
END GROUP                            5-44
END HEADING                            5-45
END REPORT                            5-45
ENTER                                5-46
EOF                                5-48
ERASE                                5-49
ERR$                                5-50
ERRNO                                5-50
EXECUTE                                5-51
EXP                                5-52
EXPORT                                5-53
FCASE$                                5-55
FILE                                5-56
FIX                                5-57
FOOTING                                5-58
FOR TO NEXT                            5-58
FORM                                5-60
FOUND                                5-60
FREE                                5-61
GET                                5-62
GOSUB                                5-62
GOTO                                5-63
GROUP                                5-64
HEADING                                5-65
HOME                                5-65
HRS                                5-66
IF THEN ELSE                            5-66
IMPORT                                5-69
INDEX                                5-70
INPUT                                5-71
INSTR                                5-72
INT                                5-74

                iv

KEY                                5-75
LABELS                                5-77
LCASE$                                5-78
LEFT$                                5-78
LEN                                5-80
LET                                5-80
LIST                                5-82
LOAD                                5-83
LOCATE                                5-84
LOG                                5-85
LOOKUP                                5-85
LTRIM$                                5-87
MAKE                                5-88
MENU                                5-89
MENU CLEAR                            5-90
MENU ON                                5-90
MERGE                                5-92
MID$                                5-92
MINS                                5-94
MOD                                5-94
MODIFY                                5-95
MONTH                                5-96
MONTH$                                5-97
NEW                                5-98
NEWLINE                                5-98
NOW                                5-99
NUMBASE                                5-100
ON ERROR                            5-100
ON GOSUB                            5-102
ON GOTO                                5-102
OPEN                                5-103
OPEN FORM                            5-104
OPEN FIELDS                            5-104
OPEN FILE                            5-105
ORDER                                5-106
OUTPUT TO                            5-109
PASSWORD                            5-110
PCOL                                5-110
POSITION                            5-111
PRINT                                5-112
PROTECT                                5-114
PROW                                5-114

                v

QUIT                                5-115
READ                                5-116
RECCOUNT                            5-116
REM                                5-117
REMOVE FILE                            5-118
REMOVE FROM                            5-118
REMOVE INDEX                            5-119
RENAME                                5-120
REORGANIZE                            5-120
REPLICATE                            5-121
REPORT                                5-122
REQUEST                                5-123
RESTORE                                5-125
RESUME                                5-126
RETURN                                5-127
RIGHT$                                5-127
RND                                5-128
ROW                                5-129
RUN                                5-129
SAVE                                5-130
SAVE FILE                            5-130
SAY                                5-131
SCRDUMP                                5-132
SECS                                5-132
SELECT commands                            5-132
SELECT CURRENT                            5-133
SELECT DUPLICATE                        5-134
SELECT FIRST                            5-134
SELECT KEY                            5-135
SELECT LAST                            5-136
SELECT NEXT                            5-136
SELECT PREVIOUS                            5-136
SELECT REMOVE                            5-137
SELECT WHERE                            5-137
Query Language Commands                        5-138
SELECT                                5-140
SER                                5-142
SET                                5-142
SET BUFFERS                            5-144
SET PAGING                            5-144
SET view mode                            5-145
SGN                                5-145

                vi

SHOW                                5-145
SIN                                5-147
SPACE$                                5-147
SQR                                5-148
STORE                                5-148
STR$                                5-150
TAN                                5-151
THOUSECS                            5-151
TIME$                                5-152
TIMEVAL                                5-152
TODAY                                5-153
TRIM$                                5-154
UCASE$                                5-154
UPDATE                                5-155
VAL                                5-156
VIEW                                5-157
WAIT                                5-157
WHERE                                5-158
WHILE WEND                            5-160
YEAR                                5-160
CHAPTER 6
QUICK REFERENCE GUIDE                        6-1
INDEX                                I-1

                vii

             CHAPTER 1 - INTRODUCTION TO DML

Welcome to Superbase Professional's Database Management Language (DML). DML
is based on the programming language Basic. It includes most of the
standard Basic commands and functions, but supplements them with a large
number of commands and functions that are specific to database management.

The database commands duplicate the controls that Superbase Professional
provides through its menus and dialogs. This means that almost all of
Superbase's file and record handling facilities are available under program
control. In fact, apart from Fast Forwards, Rewind and Duplicate, you can
now carry out any Superbase operation using a single program command.

Once you have familiarized yourself with Superbase's controls, the
corresponding program, you may find the idea of learning a program language
daunting. But as far as DML is concerned, a little goes long way, and you
do not need to be fully conversant with the language in order to take
advantage of it.

In effect, you are already following a program sequence every time you
perform a task which involves a series of menu operations. Writing a
program that performs the task for you is simply a matter of entering
commands in the same sequence. Generally, you will be able to find a single
command to duplicate each of the menu operations.

As you acquire more expertise, you can move on, building bigger and more
complex programs by combining routines, until you have fully automated your
database system. When you're ready, you can incorporate Superbase forms
into your programs, taking advantage of their built-in facilities for
generating and retrieving records in several files at once.

At the highest level, you can specify your own pull-down menus, replacing
the standard Superbase menus with the options that are relevant to the job
in hand. And you can customize your application to an even more detailed
level by creating your own pop-up selection panels to guide the user's
choices.

                1-1

USING THIS GUIDE

Before reading this guide, you will need to be familiar with Superbase's
menu and keyboard controls. Many of DML's commands provide a program
equivalent of a menu or keyboard option, and the descriptions given here
presume that you already know how to use the corresponding option.

However, once you have mastered Superbase itself, you do not need to read
this book all the way through. As a reference guide, it can be consulted as
and when it is needed.

HOW TO USE THIS GUIDE

Chapter 2, Overview, describes the most basic features of DML. You can
think of it as a grammar book for the language. It sorts DML's 'keywords'
and other components into different groups and, more importantly, sets out
all the rules for using them. For example, it specifies the maximum length
for a program line,  and gives the rules for creating variable names.

Chapter 3 explains how to use the Program Editor. This covers entering and
editing programs, storing them on disk and loading them from disk. It also
explains how to execute programs, and how to create a 'start up' program
which will be executed automatically when you start a session with
Superbase.

Chapter 4 describes Superbase's function key facility. It explains how to
define the function keys and discusses various applications for them.

Chapter 5, Keyword Reference Guide, forms the bulk of the manual. In this
chapter, you will find an entry for each DML keyword, which gives the
keyword's syntax and describes its usage. The entries are in alphabetical
order starting with the ? command. At the front of Chapter 5, there is an
explanation of the conventions used to show a keyword's syntax.

Chapter 6 is a Quick Reference Guide. It gives the syntax for each DML
keyword together with a brief description of its function.

                1-2

            CHAPTER 2 - OVERVIEW

OPERATING MODES

DML has two modes of operation: direct mode and program mode.

DIRECT MODE

In this mode, DML executes instructions as soon as you have typed them in.
First you need to select the Command option from the Program Menu. Then
enter your instructions - a single command or a line of commands separated
by colons - in the command line window; when you select 'OK' or press the
Return key, DML will carry out the instructions straight away. The command
line window is 64 characters long but you can enter up to 255 characters
and move within the window using the cursor keys.

PROGRAM MODE

In program mode, DML does not execute commands as you enter them. Instead
they are stored in memory and executed only when the program is run. The
main difference between this mode and direct mode is that with the latter
you can only enter and execute one line at time; program mode allows you to
enter a series of instruction lines which are carried out in sequence.
Program lines can be up to 255 characters long.

OTHER DML APPLICATIONS

DML's functions, along with its operators and variables, can also be used
in other Superbase operations - such as field definition validations and
calculations, filter conditions, update commands and query derived field
definitions.

KEYWORDS AND RESERVED WORDS

Any word that DML recognizes as a specific instruction, or part of an
instruction, is known as a keyword.

A keyword cannot be used as a variable name, a field name, or a label. In
this context, keywords are also knows as reserved words - DML reserves them
for its own use, and will interpret then as such even if they are in lower
case.

                2-1

A reserved word can, however, from part of a name. For example, you can
incorporate the reserved word TO in any of the following ways:

TOP:        (in a label)
TOTAL%        (a numeric variable)
tot$        (in a string variable)
TOTALS$        (in a field name)

But you cannot use it like this:

TO:
TO%
TO$

COMMANDS AND STATEMENTS

Some programming manuals make a strict division between two kinds of
executable instructions - commands and statements. Commands are those
instructions which are generally executed in direct mode, while statements
are instructions that can only appear in a program line.

In DML there are only a few instructions that cannot be used in both
operating modes and so the two terms are used almost interchangeably. Thus
we refer to a line with more than one instruction on it as a
multi-statement line; but it could equally well be called a multi-command
line.

VARIABLES

There are three types of variables in DML: string variables, numeric
variables,  and arrays. In many circumstances, the fields in a Superbase
file can also be treated in the same way as variables.

VARIABLE NAMES

Numeric variables must end with the '%' character, string variables end
with an '$' character. Apart from this, the names for both types of
variable follow the same rules:

Variable names have a maximum length of 14 characters and a minimum length
of 1 character (excluding '%' or '$').

The first character of the name must be a letter in the range 'a' to 'z'
but the remaining characters can be either alphabetic or numeric.

                2-2

DML is not case sensitive; 'abc%' is the same as 'ABC%', and 'abc$' is the
same as 'ABC$'.

A variable name can contain a reserved word, but cannot consist of just a
reserved word and the variable suffix, % or $. For example, names like
'lef$',  'cos%', 'report$' and 'FILE%' are forbidden. See Appendix A for
the list of reserved words.

Before using a variable, you must define it by assigning a value to it.
This means that the first occurrence of a variable should be in an
assignment statement, with the variable to the left of the equal sign.
Suppose, for example,  you instructed DML to display the value of a$, using
the command

    ? a$

If you have not assign a value to a$ beforehand, DML will issue the error
message:

    Can't do this
    Variable not defined

To avoid this error message, you would have to define a$ at an earlier
stage in the program, with line such as

    a$="Hello"

or

    a$=""

The double quotes are known as the 'empty string'. They allow you to define
a string variable without actually assigning a specific value; they are
also used to clear the contents of string variables.

There are, however, a number of exceptions to the rule about defining
variables. Some statements - READ, ASK, WAIT, and INPUT - define variables
implicitly when they are used for the first time. Thus DML would accept the
line:

    READ a$

even if you had not assigned a value to a$ previously.

NUMERIC VARIABLES

DML's numeric variables hold numbers at 13 figure accuracy, but if
displayed or printed, they are shown in the current default numeric format.
Note that there is only one type of numeric variable. In some versions of
Basic, the % suffix indicates that the variable can only store whole
numbers (integers): in DML, the

                2-3

same numeric variable can be used for both whole numbers and floating point
numbers.

STRING VARIABLES

String variables are used to hold ASCII characters - usually alphanumeric
text. The maximum length of data that can be held in a string variable is
255 characters.

ARRAYS

DML supports string and numeric arrays with up to three dimensions. The
maximum number of elements in an array is limited only by the amount of
memory available.

The rules for array names are the same as those for numeric and string
variables. Numeric arrays must end with '%' character, string arrays must
end with '$' character.

SYSTEM VARIABLES

TODAY, NOW and ERRNO are variables which are supplied by DML. TODAY gives
the system date, NOW gives the system time. DML treats these in the same
way as date and time fields; that is, although they are numeric variables,
they are displayed in the current date or time format. If the time of day
is 9:41 and the system clock has been set to this time. NOW would display
it as 9:41. But it stores this as 34919810 - the number of thousandths of a
second from midnight to 9:41. ERRNO returns the number of the last error
that occurred.

You cannot assign a value to a system variable, but otherwise TODAY, NOW
and ERRNO can used in the same way as any other numeric variable.

FILE TYPES

When you save a file using one of the SAVE options, DML automatically adds
one of the following extension names to the file name:

    aaa.sbf is a database file
    aaa.sbd is a file definition for a database file
    aaa.sbk is a function key file
    aaa.sbp is a program file
    aaa.sbq is a Query file
    aaa.sbt is a text file saved from the text editor

                2-4

    aaa.sub is an Update file
    aaa.### is an index (where ### is a number from 001 to 999)

DML stores program files, Text Editor files, database files and index files
in its own format (for example, it tokenizes keywords in program files and
stores formatting information with documents saved in the Text Editor). The
others are all text files and only contain ASCII characters.

FIELDS

With a few exceptions, you can use fields in the same way as variables. For
instance, you can input data directly to fields; you can supply a field
name as the argument for a function; and you can assign values to fields.

Fieldnames must conform to the rules for field names as set out in Volume
1, i.e.:

    The maximum length is 15 characters.
    The minimum length is one character.

They must begin with an alphabetic character, but can thereafter contain
any alphanumeric characters. They can also contain the underscore and space
characters. Superbase will accept a field name with several spaces embedded
in it - i.e., 'a bc d' is a valid name - but this is not recommended.

DML is not case sensitive; 'abc' is the same as 'ABC'.

The file a field belongs to must be open; otherwise the following requester
appears:

    Can't do this....
    'field name'
    Can't find this field

Where more than one file is open and there are two files with the same
field name, the file name must be given as an extension to the field name
and the two must be separated by a full stop. This enables DML to identify
the field you are referring to.

NOTE: FAILING TO SUPPLY FILE EXTENSION NAMES TO FIELDS MAY RESULT IN
INCORRECT DATA, ALTHOUGH IT DOES NOT CAUSE AN ERROR.

                2-5

If the file name contains spaces, it must be included within quotation
marks,  e.g.:

    fielda.filea
    name.Customers
    Lastname."Customer File"

DATE AND TIME

Superbase stores dates as julian date numbers; that is, as the number of
days from 31st December in the year zero. This means that date fields are
numeric fields and hold their dates as numbers. When you display a date
field, however,  Superbase automatically converts it to a more recognizable
format: it takes the format which has been set in the file definition (see
Chapter 2, Volume 1).

The date format only controls the way dates are displayed. You can enter a
date from the keyboard in almost any format. For instance, the date might
be shown on screen as 24/02/87, but you can type in a date like '28
February, 1962' and DML will accept it.

Incidentally, DML does remember that eleven days were lost when the
Gregorian Calendar reform was implemented (September 2nd, 1752 is followed
by September 14th).

As with dates, DML stores the time in time fields as a numeric value, but
displays it in a different format. The time is stored as the number of
thousandths of a second from midnight. When you display the time, it is
given in hours and minutes in either 12 or 24 hour format.

FUNCTIONS

Functions form one of the largest groups of DML keywords. Most of them
perform a calculation on a number or a string, but there are also functions
that give information about some aspect of the system. RECCOUNT, for
example returns the number of records in a file, and FREE returns the
amount of free memory space. Unlike a command, a function cannot be entered
on its own as a statement. Thus:

    ? RECCOUNT ("address")

                2-6

    NUMRECS%=RECCOUNT ("address")

are valid statements, but

    RECCOUNT ("address")

produces an error message.

All functions take an argument, which is enclosed in parentheses, and
return a result. If the function calculates a result, the argument is what
it works on. In the example above, "address" is the argument. It tells the
function which file to count.

Depending on the function, the argument (or arguments) may be a field name,
a file name, constant, a variable, or a combination of these connected by
an operator to form an expression. You will find details of what kind of
argument a function expects, in the Keyboard Reference section.

Although functions are usually classed as either string or numeric
functions,  this does not always guarantee that they take a particular kind
of argument. Numeric functions always take numeric arguments, but some
string functions also expect a numeric argument. CHR$, for example, returns
a string result from a numeric argument.

When it comes to finding out what type of result a function returns, there
is a simple rule you can apply. Functions which have a $ character at the
end, return their results as string data; if they do not end in a $, they
return a numeric result. There is one exception to this rule - REPLICATE,
which returns a string result, despite the fact that it does not have a $
at the end.

OPERATORS

DML provides three types of operators: arithmetic, relational and string.

ARITHMETIC OPERATORS

Addition

The plus sign specifies that the operand on the right is added to the
operand on the left, e.g.:

    2 + 2
    a% + b% + c%
    a% + 12.225

                2-7

Subtraction

The minus sign specifies that the operand on the right will be subtracted
from the operand on the left e.g.:

    -3
    -a%

Multiplication

The asterisk is recognised by DML as the multiplication symbol and
specifies that the operand on the left is multiplied by the operand on the
right, e.g.:

    3 * 2
    a% * b%
    a% * 12.225

Division

The slash is recognized by DML as the division symbol and specifies that
the operand on the left is divided by the operand on the right, e.g.:

    3 / 2
    a% / b%
    a% / 12.225

NOTE: UNLIKE IN MANY OTHER PROGRAMMING LANGUAGES, DIVISION BY ZERO DOES NOT
CAUSE AN ERROR MESSAGE AND RETURNS A VALUE OF ZERO. THIS, OF COURSE, IS A
FALSE RESULT,  AND YOU SHOULD CHECK NUMERICAL DATA TO ENSURE IT DOES NOT
OCCUR.

Exponentiation

The up arrow (or caret) is recognized by DML as the exponentiation symbol
and specifies that the operand on the left is raised to the power specified
by the operand on the right (the exponent); that is, the operand on the
left is multiplied by itself the number of times specified by the exponent.
If the exponent is 2, the number is squared; if the exponent is 3, the
number is cubed; if the exponent is 1/2, the square root of the number
results, e.g.:

                2-8

    3 ^ 2            (3 squared)
    a% ^ b%
    a% ^ 12.225
    a6 ^ 0.5        (the square root of 16)
    27 ^ 0.33333333        (the cuberoot of 27)
    3 ^ -2            (1/3 * 1/3)

Modulo arithmetic

MOD gives the remainder when the operand on the left is divided by the
operand to the right, e.g.:

    17 MOD 7        (returns 3)
    a % MOD b%

Parentheses

Parentheses are used to change the order in which the different parts of an
expression are calculated. Without parentheses, expressions are evaluated
in a certain order which depends on the operators they contain - some
operators have precedence over others (see the Table of Precedence). For
example, multiplication has precedence over addition; so, in the
expression:

    3 + 4 * 2

the 'four times' part is worked out first and then added to 3, giving 11 as
the result. You could alter this by enclosing '3 + 4' in parentheses:

    (3 + 4) * 2

to give a result of 14.

Parentheses must always be paired - each '('should have a matching')'.

Concatenation

When used with strings or string variables, the plus sign causes the string
specified by the right operand to be appended to the string specified by
the left operand, e.g.:

    "ABCD" + "defg"            evaluates as "ABCDefgh"

Used in this way, the plus sign acts as a string operator.

                2-9

RELATIONAL OPERATORS

Relational operators compare the values of two numbers or two strings, and
return a result which is either true or false. They are mainly used with IF
THEN and WHILE WEND statements to make a decision about whether the program
takes a particular action or not. For example:

    IF n% > 30 THEN GOSUB label

The relational operators are:

    >        greater than           12>55 is false, i.e.0
    =        greater than or equal to
    <        less than
    <=        less than or equal to       27<=27 is true, i.e.-1
    <>        not equal to           1=5-4 is true, i.e.-1
    =        equal to
    LIKE        pattern matching operator for strings.
    CONTAINS    pattern matching operator for text files.

As far as the user is concerned the result of comparison is either true or
false. But when DML comes to evaluate a comparison, it actually assigns a
numeric value to the result. If the result is true, DML assigns it the
value of -1; if false, it assigns the value of 0. This means that if you
enter the statement:

    ? 8>5

or

    ? "F"=LEFT$ ("FRIDAY", 1)

DML will display -1. If the result of a comparison is false, it will
display 0. For string operands, comparison is character by character from
the left where 'a' is less than 'b' is less than 'c' and uppercase
characters are less than lower case characters ('A" is less than 'a'). Note
that numeric data can only be compared with numeric data and string data
can only be compared with string data. If you attempt to compare numeric
data with string data then the message:

    Can't do this/Data types don't match

appears.

                2-10

LIKE

LIKE is a case insensitive pattern matching relational operator which is
used to compare string data. The question mark '?' and asterisk '*'
characters can be used as wildcards. The question mark matches single
characters and the asterisk '*' matches multiple characters.

For a full explanation of how to use LIKE, see Volume I, Appendix B.

CONTAINS

CONTAINS works in the same way as LIKE, but it used with ASCII files on
disk; for example, you could use the expression:

    CONTAINS "*Smith*"

to search for an ASCII file which contained the name Smith. See Chapter 9,
Volume 1, for more details.

LOGICAL OR BOOLEAN OPERATORS.

Logical operators are most frequently used to modify the results of
relational operators. An expression that contains a relational operator can
either be true or false. With a logical operator you can create more
complex expressions whose truth or falsity (their 'truth value') depends on
the truth or falsity of one or more relational expressions.

AND

This operator allows you to test whether two comparisons are true at the
same time. For example:

    12 > 5

and

    6 < 16

are both true, so

    12 > 5 AND 6 < 16

is also true.

                2-11

NOT

NOT reverses the truth or falsity of an expression. Thus:

    12 < 5

is false, so

    NOT 12 < 5

is true.

NOT is often used with the EOF function to set up a program loop for
processing all the records in a file, e.g.:

    WHILE NOT EOF ("address")
    SELECT NEXT
    VIEW
    WEND

OR

OR gives a true result if one or the other, or both, of its operands is
true. For example:

    12>5 OR 12<5
    8=2*3 OR 6>5
    8=2*4 OR 6<5

all give true results.

    12>5 OR A$="LONDON"

gives a true result whatever the value of A$.

    8=2*3 OR 12<5

gives a false result.

Logical operators can also be used with numeric expressions to give a
result which depends on the binary digits of the operands. In this context,
they are sometimes known as bitwise operators. Instead of comparing the
truth or falsity of expressions, AND and OR - when used as bitwise
operators - compare the binary digits of two numbers, while NOT takes a
single number, and changes each binary 1 to 0, and vice versa. Thus AND
returns binary 1, if and only if, the corresponding digits in the two
operands are both 1, e.g.:

    85 AND 19

gives a value of 17.

                2-12

    85 in binary is 01010101
    19 in binary is 00010011

The result is 00010001 which is 17

TABLE OF PRECEDENCE

Complex expressions, containing more than one operator and several simple
expressions, are evaluated according to the following table. The higher up
the table an operator is, the higher the precedence it is given. This means
that if there are two simple expressions, the one whose operator has the
highest precedence will be evaluated first.

    ^        Exponentiation
    */        Multiplication and Division
    MOD        Modulo arithmetic
    +-        Addition and Subtraction
    <> <=> =    Relational operators
    LIKE CONTAINS    Relational operators
    NOT        Logical NOT
    AND        Logical AND
    OR        Logical OR

Where identical weighted operators are concerned evaluation will be from
left to right e.g.:

12 + 3-2    is evaluated as    12 + 3=15 : 15-2=13
12 + 3*4    is evaluated as    3 * 4=12 : 12 + 12=24
12 + 3*4-2    is evaluated as    3*4=12 : 12 + 12=12 : 24-2=22

Parentheses can be used to promote expressions up the table, e.g.:

(12+3) * (4-2)  evaluates as   15*2=30

CONSTANTS

The fixed values that you assign to variables or use as part of an
expression are known as constants. There are two types: string constants
and numeric constants. String constants must be enclosed in quotation
marks. DML also provides a ready-defined constant PI, which has the value
of 3.141593265359 and can be used in numeric calculations.

                2-13

EXPRESSIONS

Expressions are formed from any combination of:

Fields
Variables
Constants
Functions
Operators

An expression can consist of a single variable name, a field name, or a
constant,  or it may be more complex, combining these with operators,
constants and functions. The following are examples of expressions:

396
TODAY
a$
"31 Ambleside Drive"
textfielda
numfielda
Firstname.address
LEFT$ (Firstname.address, 1)
3.44*22.8 + 450
"Mr" + A$
A$ + B$
a%<>b%
(a$=b$) AND (c%=1)
INT (RND (1) *26) +1
COS (n%)

LINE FORMAT AND LABELS

There are no line numbers in DML; instead, to provide a reference for GOTO
and GOSUB commands (or ON GOTO and ON GOSUB commands) you can place a label
at the front of a line. Labels can be any combination of alphanumeric
characters but cannot contain spaces.

Labels must end in a colon (':') unless they consist only of numeric
characters. You can use a number as a label without adding a colon, but
this will not have the effect of altering the sequence of program lines.
So, if you enter a line with the label '30' after a line with the label
'50', both lines will remain in that order.

A DML line, whether in direct mode or program mode, can contain more than
one statement, provided the statements are separated by colons.

                2-14

Labels, however, can only be used in program mode.

Any command which is placed at the beginning of a multi-statement line
should be followed by a space. If it is followed by a colon without an
intervening space, DML may interpret it as a label. For example, in the
line:

    CLS: STATUS

the command CLS has no effect, but

    CLS: STATUS

works as intended.

You also need to insert a space before an expression - a variable name or a
field name, for example - if it is preceded by a DML command word. But
otherwise in program mode, DML will accept lines without any spaces in them
(it inserts spaces when it parses a line).

In direct mode, it is generally necessary to insert spaces between the
various elements of a command line.

SYNTAX

The Keyword Reference section gives the exact syntax for each keyword.
However,  there are several rules that apply generally.

FILE NAMES AND FIELD NAMES

Wherever a command is followed by a file name - or takes a file name as one
of its arguments - the file name must be enclosed in quotation marks.
Fieldnames should not be in quotation marks.

For most operations, you should not include the extension name for a file
(the part of the name after the full stop). Superbase automatically looks
for files with the appropriate extension; so, with the command:

    OPEN FILE "Address"

it looks for the file "Address.sbf".

The one exception to this rule is when you are dealing with text files.
OPEN FOR INPUT/OUTPUT, OUTPUT TO, IMPORT and EXPORT all take data to or
from text files, and require that file names are given in full.

If you save a file from Superbase's text editor, it automatically adds an
'.sbf' extension to the file name - and when you open a file from the text
editor, you do not need to supply the '.sbt' extension. But when you make
use of a text

                2-15

editor file in some other applications - with IMPORT, for example - you
must remember to include the .sbt extension. By the same token, you will
not be able to load text files into the text editor unless you give them a
.sbt extension.

UPPER CASE AND LOWER CASE

Certain string functions such as INSTR are case sensitive, but otherwise
DML ignores the difference between lower and upper case letters (small
letters and capital letters). In other words, it does not matter whether
you use lower or upper case letters when you type in a keyword or any of
the following:

    variables
    file names
    field names

It is a good idea, though, to enter program lines and direct command lines
in lower case. Once DML has accepted a line, it converts any reserved words
(that is, any keywords) to upper case. Typing in lower case allows you to
check that you have not used a reserved word by mistake.

                2-16

            CHAPTER 3 - THE PROGRAM EDITOR

THE PROGRAM MENU

Operations relating to programs and programming are controlled from a
single menu at the right of the menu bar, the Program menu. This section
lists the Program menu options, and gives a brief explanation of their
functions. Apart from Print and Remove (which should not require further
explanation), each option is also described in more detail in the sections
that follow.

COMMAND    Opens the Command line window, allowing the user to enter program
    instructions as direct commands.

RUN    Runs the program in memory or, if there is no program in memory,
     loads a program from disk and runs it.

NEW    Opens the Program Editor window and clears any program that may be
    in memory.

EDIT    Opens the Program Editor window.

OPEN    Loads a program from disk into memory.

CLOSE    Clears the program in memory - the program that is currently in the
    Program Editor - and closes the Program Editor window.

SAVE    Saves the program in memory to disk.

PRINT    Prints the program in memory.

REMOVE    Deletes a program file from disk.

THE PROGRAM EDITOR WINDOW

When you select Edit or New from the Program menu, Superbase opens a window
at the right-hand half of the screen. This is the program window where you
enter and edit programs (see next page).

In most respects, the program window can be treated in the same way as the
text window: you use the same controls for closing, resizing and moving the
window (as explained in Chapter 10, Volume 1); and you also use many of the
same key

                3-1

controls for editing a program. In fact, both the Program Editor and the
Text Editor make use of the same window. The window can only be occupied by
one of them at a time, but any changes you make to the size or location of
the window will apply when you switch to the other editor.

The main difference between the two is that the Program Editor does not
have its own set of menus. The Program menu is available at all times -
except when the Text Editor menus are active - whether the program window
is open or closed.

As with the Text Editor, you can switch between the program window and the
database window simply by moving the mouse pointer to the required window
and clicking in it. Thus, to edit a record after opening the program
window, you would click twice in one of the fields displayed in the
database window - once to make the database window active, and once to
activate the record editing cursor (on the Amiga, you would only need to
click once). If you then wanted to return to the Program Editor, clicking
once in the program window would make the program cursor active again.

Notice that the Close option on the Program menu not only closes the window
but also removes the current program from memory. If you wish to close the
window without clearing the program from memory, click on the close window
gadget at the top left-hand corner.

                3-2

NOTE: Screen output from a Superbase program is displayed in the database
window. If there is a record in view, program data will be output below or
to the right of the bottom line of record data. To clear the database
window before displaying program data on screen, use the CLS command.

CREATING A NEW PROGRAM

Selecting Edit from the Program menu opens the program window and places
the program cursor at the top left-hand corner. When you enter the Program
Editor for the first time in a session, the window will be empty; you can
then start entering program lines straight away. If you have previously
loaded a program into memory and want to start afresh on a new program,
select New to clear the existing program from memory.

Entering program lines is simply a matter of typing them in at the
keyboard. When you have typed in a line, pressing the Return key will take
you to the start of the next line.

Superbase accepts program lines up to 255 characters long. As you type
characters beyond the right-hand edge of the window, the program will be
scrolled to the left. Using the scroll bars enables you to move the window
over any part of a line up to 255 characters.

LINE FORMAT

An explanation of the correct format for a Superbase program line is given
in Chapter 2, Line Format and Labels. However, it is worth repeating th
rule about inserting spaces in a line: you need to insert a space if you
enter an expression - such as a variable name, a field name, or a constant
- after a keyword, or if you enter two adjacent keywords. In the following
example, the space between the two items on the line must be entered by the
user:

    ? "Hello"

You should also type a space between a command and a colon if the command
is placed at the start of a multi-statement line. If you do not do this,
DML will interpret the command as a label.

Otherwise, you can ignore spaces as you type in a program. If a line
contains adjacent variables or operators and other elements of an
expression, DML inserts spaces between them when it 'parses' the line.

Parsing refers to the process which takes place when you press Return or
move the cursor away from the current line. DML scans the line and
identifies the various elements in it. As well as inserting spaces between
recognizable

                3-3

elements, it also converts any keywords that are entered in lower case to
upper case. Thus if you typed:

    if a%=3.5+6then goto label1

DML would parse this line as:

    IF a%=3.5+6THEN GOTO label1

You are recommended to enter program lines in lower case as a way of
ensuring that you do not use reserved words as labels or variables. When a
line is parsed, you will be able to see at a glance whether these items are
correct,  because the reserved words will be shown in upper case.

It is unlikely that you will need to create programs with lines over 200
characters long. However, if you do, it is important to bear in mind that
spaces may be inserted in the line. Even though the line you type in is
less than 255 characters, it may exceed this limit when it has been parsed.

EDITING A PROGRAM

The Program Editor uses the same key controls for editing a program and
moving the cursor around the screen as the Text Editor. As you would
expect, it is not possible to specify margins or reformat a program; and the
style setting functions are not available. Otherwise, the only difference
is in the way the Return key works. In the Text Editor, Return either moves
the cursor to the start of the next line or creates a new line, depending
on whether overwrite or inset mode has been selected.

In this section, we only provide a list of the Program Editor key controls
together a brief description of their functions. For a detailed explanation
of these keys, see Chapter 10, Volume 1. The '^' character is used here to
represent the CTRL key (Control on the Atari ST); ^N for instance,
indicates that the CTRL key and the letter N should pressed in combination.

MOVING THE CURSOR

As with the Text Editor, you can move the cursor around the screen and edit
a program at any point on the screen.

The cursor keys are used to move the cursor by one character at a time.
Note that the term character includes the space character.

                3-4

LEFT ARROW        Moves the cursor to next character to the left.

RIGHT ARROW        Moves the cursor to the next character to the
            right.

UP ARROW        Moves the cursor to the character in the same
            column on the line above.

DOWN ARROW        Moves the cursor to the character in the same
            column on the line below.

For larger cursor movements, use the following keys:

^B            Takes the cursor to the first line in the text.
^G            Takes the cursor to the last line in the text.
Home (GEM)        Moves the cursor to the beginning of a line.
Clr Home (GEM Atari)    Moves the cursor to the beginning of a line.
Shift right cursor (Amiga)  Moves the cursor to the beginning of a line.
End (GEM)        Moves the cursor to the end of line.
Insert (GEM Atari)    Moves the cursor to the end of line.
Shift left cursor (Amiga)  Moves the cursor to the end of a line.
Tab            Moves the cursor eight characters to the right.
Shift Tab        Moves the cursor eight characters to the left.
Control T        Moves the cursor eight characters to the left.

DELETING AND INSERTING

The following keys are used for deleting and inserting program lines or
parts of a program line:

BACKSPACE        Delete character to the left of the cursor.
DEL            Delete character to the right of the cursor.
^W            Delete word.
^E            Delete to end of line.
^D            Delete line.
^X            Clear line.
^N            New line.
^S            Split line.
^A            Join line.
^V            Insert mode on/off.
^U            Undo.

Note that Undo works in the same way as in the Text Editor, and can be used
as a 'cut and paste' facility, allowing you to move multiple program lines
to a new position.

                3-5

USING THE COMMAND LINE

Selecting the Command option on the Program menu presents you with the DML
Command Line dialog. Any commands you type in the command line box will be
executed as soon as you click on OK or press Return; that is, they will be
executed as direct commands.

The command line box accepts single or multi-statement lines (with
statements separated by colons) up to 255 characters. You can type in
commands when ever the cursor is present. If the cursor is not shown, click
in the box to activate it.

There is very little restriction on which keywords can be entered as direct
commands. READ (and DATA), GOSUB, and ON GOSUB cannot operate as direct
commands,  and you cannot use labels in the command line. Apart from these,
almost any single or multi-statement line that can be entered in a program
can also be entered in the command line.

Clearly, any statement that refers to another statement in the command line
will not operate, because of the absence of labels. However, it is possible
to enter GOTO statements which refer to labels in the current program. You
may want to do this when you are testing a program. The normal way of
executing a program - using the RUN command or Run option - clears the
program's variables. GOTO allows you to execute a program or part of a
program without destroying any variable assignments that may have already
been made.

You will use the command line for variety of purposes. There are some
operations - such as appending a text or program file to a file in memory -
which can only be performed using commands. You may also want to enter
commands as an alternative to selecting options from the Superbase
menus; but it is generally more practical to do this by assigning the
commands to a function key.

In addition, the command line is valuable tool for developing and testing
programs. Particularly useful are commands such as:

    ? MEMORY

and

    ? LIST

The first command lists the current program's variables and their
values; the second can be used to display the program listing in the
database window.

                3-6

EDITING THE COMMAND LINE

The cursor keys move the cursor in the command line one character at a
time. Home (Clr Home on the Atari ST) and End (Insert on the Atari ST) take
the cursor to beginning and end of the command line. Del deletes the
character in front of the cursor, Backspace deletes the character before.

If you make a mistake while typing in the command line, you can use these
keys to correct it. Command lines remain in the box after they have been
executed and function key commands are placed in the command line box after
execution, so you may also want to recall the previous command for editing.

LOADING A PROGRAM

To load a program from disk into the Program Editor, select Open from the
Program menu. A file dialog will appear, listing the names of the program
files in the current directory. You can then select a file in the usual
way. If you want to load a program in another directory or on another disk,
type in the file name preceded by the path name.

To append a program on disk to program in memory, select the Command option.
Then enter:

    LOAD "programname", APPEND

where "programname" is the name of the program on disk which is to be
joined to the current program.

Most of the programs you run will have been created in the Program Editor.
However, it also possible to load a program which has been written in a
word processor, or has been created in another program editor. In this
case, there are two requirements: the program file must have an '.sbp'
extension, and it must be an ASCII file.

Note that Open loads a program into the Program Editor, but it does not
open the Program Editor window. If the window is closed and you wish to
edit a program after loading it, select Edit.

SAVING A PROGRAM

Save on the Program menu saves the current program on disk. When you select
this option. Superbase displays a dialog where you type in the name under
which the program is to be saved.

                3-7

Normally, programs are saved on disk in 'tokenized' form; instead of storing
each character in a keyword, Superbase represents keywords using single
character tokens (keywords are represented in this way internally as well
as on disk). To save a program as an ASCII file, enter in the command line:

    SAVE "program name", TEXT

ASCII program files can be loaded back into the Program Editor and run
straight away. Note that all program files, both tokenized and ASCII files,
are given an '.sbp' extension.

RUNNING A PROGRAM

Select Run from the Program menu to run the program in memory. If there
isn't a program in the Program Editor, Run displays the program file
dialog. When a program has been selected, it is loaded into memory and then
executed.

The DML command RUN provides the program equivalent of the menu option. It
is generally entered as a direct command, but it can also be used within a
program. As a program command (rather than a direct command), RUN allows
you to perform a task by linking together a series of programs. When one
stage has been completed, RUN followed by a program file name will load and
execute the program which performs the next stage.

However, the drawback to using RUN for this purpose is that loading and
executing a new program clears the previous program's variables. If you
want to link a number of programs together, it usually preferable to use
the CHAIN command. This provides the same facility as RUN but has the
advantage that it does not clear any existing variable assignments.

CREATING A START UP PROGRAM

One of Superbase's most useful features is the way it lets you specify a
'start up' program, which will be automatically loaded and executed when
you run Superbase. There are many ways in which you can take advantage of
this feature,  especially if you use Superbase on a regular basis for a
specific application. All the tasks that you need to perform at the start
of a session - such as opening files and loading a function key set - can
be taken care of by the start up program.

                3-8

The procedure for creating a start up program is straightforward. There are
two requirements:

The program must be stored in a directory where Superbase will find it:
either the Start directory as specified in Options on the Set menu (see
Chapter 7,  Volume 1) or the directory which is current when Superbase is
loaded; usually this will be the same directory as the Superbase program
file.

The program must be saved under the file name Start (this appears on disk
as Start.sbp).

When you run Superbase, it looks in the current directory for a program
with the name Start. If you have specified a Start directory in the '.par'
file, it then looks for the program in that directory.

EXAMPLES

LOAD KEY "Funkey1"
OPEN FILE "Address"
OPEN FILE "Customers"
SET TABLE
VIEW

This program loads a function file, opens two database files, set Table
View, and then displays the first record in the Customers file.

LOAD KEY "Funkey1"
NUMBASE "z999999."
RUN "Prog2"

After loading a function key file, this program sets the numeric format and
then loads and executes prog2.

                3-9

            CHAPTER 4 - FUNCTION KEYS

With Superbase's function key facility, you can create a new set of key
controls. Each function key may be assigned a string of up to 255
characters. Depending on the context, Superbase will interpret the string
either as a command (or sequence of commands) or as text.

The main applications for this facility are:

Creating command sequences - one line programs - to provide keyboard
equivalents for the Control Panel buttons and menu options.

Creating more complex command sequences which will perform multiple
operations with a single key-stroke.

Inserting often-used words, keywords, phrases, and paragraphs in a text
document or a program.

The number of functions keys you can define depends on which version of
Superbase is used. All versions provide the function keys F1 to F10. In
addition, Amiga and Atari owners can use the Help key, which may be
regarded as key F0. Another set of ten function keys is available when you
use F1 to F10 in combination with the Shift key. On Gem versions of
Superbase running under MS DOS, you can also use the CTRL and Alt keys in
combination with the keys F1 to F10.

To summarize these differences:

21 function keys are available to Amiga and Atari owners; F1 to F10 plus
Help, and Shift F1 to Shift F10.

MS DOS computers have 40 function keys; F1 to F10, and the same keys in
combination with Shift, CTRL or Alt.

SETTING A FUNCTION KEY

There are two ways of setting a function key: using the Set Menu option
Function keys (Function keys Edit on the Amiga), and using the DML command
KEY. With the first method, you select Function keys from the Set menu. You
will then be presented with the Function key dialog (see next page).

This shows the dialog for GEM versions of Superbase running under MS DOS.
Atari versions have three keys at the right: Help, Down arrow and Up arrow.
In both

                4-1

MS DOS and Atari versions, the Up arrow symbol is used to represent the
Shift key. The Down arrow represents Shift off; clicking on this key
highlights it and turn Shift off.

On the Amiga, the four keys at the right of the panel are replaced by the
HELP and Shift keys.

On entry to the dialog, the F1 key is highlighted (as is the down arrow key
on GEM versions). Clicking on one of the other keys, F2 to F10 (and HELP on
the Amiga and Atari), highlights the key, making it available for setting.
You can then assign a string to the key by typing it in the entry box
below. Click in the box first if the cursor is not shown.

Clicking on Shift (or the Up arrow symbol) highlights it; you can now assign
a string to one of the key combinations Shift F1 to Shift 10. For the Amiga
and the Atari, the Shift key is the only one that can be used in
combination with the keys F1 to F10 - Shift HELP is the same HELP on its
own. On MS DOS  machines, you also have the choice of selecting CTRL and
ALT. This makes available the key ranges CTRL F1 to CTRL F10 and ALT F1 to
F10.

When you have set the functions keys you require, click on OK. This action
will assign the strings you have entered to their respective keys and then
remove the dialog.

The other method of setting the function keys is to use the DML command KEY
- either from the Command Line or from a program. Consult the keyword
reference entry under KEY for an explanation of how to use this command.

FUNCTION KEYS FOR COMMANDS

As we mentioned earlier, Superbase treats function key assignments as
commands or text according to the circumstances. If one of the editing
cursors is active, a function key string is interpreted as text; if a cursor
is not present,

                4-2

a string is executed as a command. There are three circumstances in which
an editing cursor may be active: when you are editing a document in the
Text Editor, or a program in the Program Editor, and when you are editing a
field in record edit mode.

The rules governing the commands which can assigned to function keys are
the same as for the Command Line (see Chapter 3). If the commands can be
executed as a one line program, they can also be assigned to a function
key. Note that single word commands at the beginning of a function key
string must have a trailing space if followed by a colon.

EXAMPLES

The following function key strings show how you can create keyboard
equivalents for the Control panel buttons:

SELECT FIRST: VIEW

This has the same effect as clicking on the First record button.

SELECT LAST: VIEW

Equivalent to the Last Record button.

a%=0: a$=" ": REQUEST "Locate key", "", 4, a%, a$, 20:
IF a$ <> " " THEN SELECT KEY a$: VIEW

Equivalent to the Key Lookup button. The REQUEST command is not necessary
for this purpose, but it allows you to display a customized dialog, making
the operation of using an index key easier to perform.

It is worth pointing out that the command KEY lists all the current
function key assignments to the current output device. You may find it
useful to assign this command to one of the function keys. Enter the single
KEY as the function key string. Pressing the key will then show you at
glance what the settings are for the other keys.

FUNCTIONS KEYS FOR TEXT AND PROGRAM ENTRY

In text entry, Function keys are useful for entering text strings which
occur many times in the same document or are regularly used in different
documents. They save you the trouble of having to type in the string
yourself every time it is needed. Provided the text cursor is shown on
screen, pressing a function key will insert a string at the point where the
cursor is located.

The same applies to the use of function keys in program entry. You can
define function keys to insert commonly used keywords in a program. For
example, you

                4-3

might want to define the keys F1 to F5 as:

REM
LOAD "
SAVE "
OPEN FILE "
WHILE

Keys F5 to F10 could then be assigned commands which are useful during
program development (you would have to activate the database window before
these could be executed):

MEMORY
RUN
PAGING ON: ? LIST
EDIT
STATUS

If you wish to assign a text string that runs over several lines, you need
to use the carriage return character. However, it is not possible to enter
this character in the Function keys dialog, so you must enter it using the
KEY command in a program or in the Command Line. Thus to assign an address
to F1,  you enter a string like this:

KEY 1, "6 Park Terrace " + CHR$ (13) + "Worcester Park" +
CHR$ (13) + "Surrey KT4 7 JZ" + CHR$ (13)

NOTE: In most cases, function key strings which are intended for text entry
cannot be executed as commands. Pressing a function key of this type when
the cursor is not active may cause an error message.

EDITING A FUNCTION KEY STRING

If a function key has already been set, selecting the Function keys option
(Function keys Edit on the Amiga) from the Set menu displays the contents
of the key in the string entry box. Initially, the setting for the F1 key
will be shown. In Gem versions, when you select another key, Superbase
displays the setting for that key.

If you wish to change the current setting, you can do so using the same
editing controls as for the Command Line: cursor keys, Backspace, Del, Home
and End. Alternatively, click on Clear to remove the current setting and
type in a new function key string.

Remember to press the Return key after editing a function key; otherwise
your alterations will not be registered.

                4-4

FUNCTION KEY FILES

The strings you assign to the functions keys can be saved on disk for use
in other sessions with Superbase. Function key files are saved as ASCII
files with the extension '.sbk'. If you wish to examine a function key
file, you may display it on screen or print it out with the List option on
the System menu. Notice that any keys which have not been assigned a string
are shown as blank lines.

SAVING FUNCTION KEY FILES

Selecting the Function keys Save option saves the current function key
settings on disk. Superbase adds the '.sbk' extension to the file name you
type in. Function keys Save presents you with a file dialog, showing the
existing '.sbk' files in the current directory. This operates in the same
way as any other file dialog. If you select a file name from the list -
instead of typing in a new name - a dialog will appear, asking if you wish
to overwrite the selected file. You can then click on OK to overwrite, or
Cancel to halt the operation.

LOADING FUNCTION KEY FILES

Select Function keys Load from the Set menu to load a function key file
from disk. A file dialog will appear showing the '.sbk' files in the
current directory. After a file has been selected, it is loaded into memory
and sets the current function keys.

The LOAD KEY "file name" command is used to load a function key file under
program control or from the Command Line. Once you have created the
function key set that meets your requirements, you can include this
command, followed by the name of the function key file, in the Start
program (see Creating a Start up program, Chapter 3). This way, the
function keys will be set up for you as soon as Superbase has loaded.

Another way of using the LOAD KEY command is to assign it to a function
key. You will then be able to load a specified function key file with a
single key press.

                4-5

            CHAPTER 5 - KEYWORD REFERENCE GUIDE

SYNTAX CONVENTIONS

This section describes the conventions that have been used in the following
documentation.

The general format used to explain each keyword is as follows:

PURPOSE -a brief description of the keyword.
SYNTAX - the format of the keyword.
COMMENTS - explains the format and function of the keyword in more detail.
EXAMPLES - program examples.
NOTES - explains the program examples and covers any other points not dealt
with under the above headings.

For the syntax of the keyword, the following terms and symbols are used:

nexpr

This can be any valid numeric expression consisting of numeric fields, date
fields, numeric constants and/or numeric results of other keywords. For
example, if a function expects a numeric argument, you could enter any of
the following expressions:

    156        (an integer)
    156.25        (a floating point number)
    num%        (a numeric variable)
    numfield    (the name of a numeric field in a file)
    3 + 6        (the result of an expression)
    SQR (25)    (the result of a keyword)

strexpr

This can be any string or substring from a text field, external field,
string variable, text literal or string result of other keywords. For
example, any of the following expressions would be suitable entries for
strexpr:

    "hello"        (a string constant)
    strfield    (the name of a string field)
    numfield    (the name of a numeric field)
    fielda$        (a string variable)

                5-1

    fielda$        (a string variable)
    Address        (a file name)
    MID$ ("immediately", 3, 2)  (a calculated result)

var

This can be any variable, string or numeric. If the keyword requires
variables of a particular type, strvar or nvar are used for string or
numeric variables. Various other conventions - such as fieldname or just
field - are used to indicate particular data types. These should be
self-explanatory.sbfile, for example, means that you should enter the name
of a database file; on disk,  Superbase identifies database files by an .sbf
extension, but you should not include the extension name when you use it in
a DML command.

Any parameters or arguments contained in parentheses are compulsory
(including any commas), while those within square brackets- '['and']' - are
optional. All other arguments are compulsory. For instance, supposing the
syntax for a keyword is given as:

    XXX (strexpr$, nexpr[.nexpr2])

This means that strexpr and nexpr are required with the keyword XXX and
that they must be separated by a comma. The next argument, nexpr2, is
optional, but if used must be separated from the second argument by a
comma.

The '/' character is used to indicate a number of alternatives. For
example:

    CLOSE ALL/FILE sbfile

The syntax for this statement indicates that CLOSE can be followed by
either ALL or FILE, but not both at the same time.

                5-2

? COMMANDS

? is a general purpose output command. You can use it to display
information on screen, or to send information to the printer, or to create
a file on disk. When ? is followed by a list of expressions - text,
numbers, variables, fields, etc it sends the expressions to the current
output device. It can also be used with the following keywords:

    DIRECTORY
    LIST
    MEMORY
    QUERY
    STATUS
    TEXT

These keywords have a specific function when used with ?, and have been
treated as separate commands. You will find an entry for each of them
further on in this section.

CHANGING THE OUTPUT DEVICE

When you load Superbase, the ? command takes the screen as the default
device and works in the same way as the PRINT command does in other
versions of Basic - it displays information on screen. If you want to
direct output to another device use one of these commands first:

    PARAMETER        PURPOSE
    PRINT            for the printer
    OUTPUT TO        for the disk drive
    DISPLAY            to switch back to the screen

? then continues to output to the device selected by one of these commands.
CLS and HOME do not reset the current output device.

PRINT and DISPLAY can be followed by a list of expressions which will then
be output to the devices associated with these commands. When you use PRINT
and DISPLAY simply to change the current output device, they should be
followed by a semicolon, as in:

    PRINT;

which directs all future output to the printer.

OUTPUT TO needs a filename after it, as in:

    OUTPUT TO "texta"

which directs output to a file on disk named 'texta'.

                5-3

OUTPUT FORMAT PARAMETERS

After outputting a list of expressions, the ? command starts a new line
unless you specify otherwise. This means that it takes the cursor to the
beginning of the next line (if the current output device is the screen).
You can instruct DML to output the next list of expressions on the same
line, by placing a semicolon at the end of an expression list. When it is
used in this way, the semicolon is known as an output format parameter, and
is one of a number of parameters that allow you to specify how output is
formatted.

Apart from the semicolon, you place these parameters in front of the
expressions that you want to format. Thus you can place them at the front
of the line immediately after the ? character, and you can also insert them
in the middle of an expression list.

Some output parameters are keywords such as BF and DOWN, and others are
symbols such as the semicolon itself and the @ sign. If you use keyword
parameters, they must separated from each other by spaces. For example, DML
will accept a line like this:

    ? UL BF IT "One", , "TWO' UL OFF @5, 10"Three"

but it will not accept

    ? ULBFIT"One", , "Two"ULOFF@5, 10"Three"

The output format parameters for the ? command are:

PARAMETER        PURPOSE

&            Sets length of text string
@            Sets row and column position
,             Outputs a space
;            Used as a separator and to suppress new line
DOWN            Outputs each item on a new line
ALL            Outputs all the fields in the current record
NEWLINE            Starts a new line
BF[ON]            Sets text to bold face
UL[ON]            Underlines text
IT[ON]            Sets text to italic
BF/UL/IT OFF        Turns selected text attribute off
ATTR OFF        Turns all text attributes off
FG (Amiga only)        Sets foreground color
BF (Amiga only)        Sets background color
SAY (Amiga only)        Speaks output
EJECTnn            Outputs data on a new page if there are less than
            nn lines left at the bottom of the page

                5-4

COMMENTS

The @ sign, followed by a numeric expression, specifies the column and row
position for your output. For example, if the screen is the output device
selected:

    ? @12, 7"Smith"

displays the name Smith on the screen at column 12, row 7. As an
alternative to using @, see LOCATE.

DML treats a comma as a space character. For example:

    ? "Hello", , , "goodbye"

outputs

    Hello   goodbye

Placing a semicolon after the last expression in the output list prevents
DML from outputting a new line character. For example:

    ? "Hello": ? "there"

outputs them on the same line as

    Hello there

Note that when the output device is the screen, DML only outputs the
expressions in a list when it starts a new line. For example, if you enter
the line:

    ? "one"; "two"; "three";

nothing will appear on the screen until you enter another line which does
not have a semicolon at the end of it.

If used, DOWN must be placed at the front of a line, before the line's
expressions and after the ? character. It ensures that each expression in
the list is output on a new line. For example:

    ? DOWN "one"; "two"; "three"

nothing will appear on the screen until you enter another line which does
not have a semicolon at the end of it.

If used, DOWN must be placed at the front of a line, before the line's
expressions and after the ? character. It ensures that each expression in
the list is output on a new line. For example:

    ? DOWN "one"; "two"; "three"

formats the output on screen as

    one
    two
    three

                5-5

When Down is used to format field data, it displays the field names in inverse
video at the left of the data - in same way as Record View displays a record.
ALL outputs the fields in the current record; for example, if the screen is the
current output device:

    ? DOWN ALL

would have the same effect as clicking on the current record button when
Record View is selected.

NEWLINE instructs DML to start a new line. Thus

    ? "one", "two"NEWLINE "three"

outputs the expressions as

    one two
    three

NEWLINE can also be used on its own - see NEWLINE, Keyword Reference.

BF, UL, and IT set the text style for output.
BF    sets boldface
UL    sets underline
IT     sets italic

Each of these can be set by ON (which is optional) and cleared by OFF.

ATTR OFF clears all the text style attributes.

For example:

    ? BF"Bold face on"; IT "italics on"; BF OFF IT OFF "Bold and italics
off" On the Amiga you can also set the foreground and background colours,
using FG and BG. Each takes a parameter in the range 1 to 4 for the four
colours set by Preferences. For example:

    ? FG 2 BF 1 "Foreground colour 2, background colour 1"

SAY, which is only available on the Amiga, uses the Amiga's narrator device
to speak the items in an expression list. Thus if you wanted to speak the
field names and field data for the current record, you would enter:

    ? SAY DOWN ALL

EJECT can be used to ensure that a group of data items - the fields in a
record, for example - all appear on the same page. For example:

                5-6

    ? DOWN "One"; "Two"; "Three"; "Four" EJECT 4

displays a new page if there is not enough room at the bottom for the four
items in the expression list.

                5-7

?

PURPOSE

Sends information to a device.

SYNTAX

? [@nexpr] [; expr; expr, ....]

COMMENTS

Used to send one or more expressions (an expression list) to the current
output device. ? can also include any of the output format parameters.

When you output numeric, date, and time constants or the results of
functions for these data types, they take the format which has been set
with the Number or Date/Time format options on the Set menu (or with the
commands NUMBASE and DATEBASE). Field data is output in the format set in
the file definition. However, you can force Superbase to output field data
in the current format by enclosing the field name in brackets. Thus:

    ? (numfielda), (datefielda)

displays the contents of these fields in the current numeric and date
formats rather than in the formats they have been given in the file
definition.

EXAMPLES

1    ? "Hello"
2    ? "Hello"; a$
3    ? UL BF "Hello"; a$; NEWLINE b$
4    ? "The square root of"; n%; "is"; SQR (n%
5    ? "One""two""three"

NOTES

Depending on the numeric format that has been set, example 4 would output
the numeric expressions, n% and SQR (n%), with leading spaces. To remove
these, you would have to use the STR$ and LTRIM$ functions.

You will notice that there are no semicolons separating the expressions in

                5-8

example 5. It is not always to place a semicolon between two expressions.
Provided DML has some other way of telling where one expression ends and
the other one starts, you can omit the semicolon. In this example the
quotation marks allow DML to distinguish between the three expressions.

? DIRECTORY

PURPOSE

Lists the current directory to an output device.

SYNTAX

[?] DIRECTORY

COMMENTS

When the screen has been selected as the current output device, the
directory is listed in two columns in alphabetic order. If the output
device is the printer or a disk file, the directory is listed in single
column.

The "?" command is optional - DIRECTORY on its own has the same effect.

? LIST

PURPOSE
List a program in memory to an output device.

SYNTAX
? LIST

COMMENTS

Do not confuse this command with LIST, which displays a text file on
screen. ? LIST has several applications. You can use it to examine a
program listing by displaying it on screen on printing it out; and, when the
current output device is the disk drive, it allows you to save a program as
a text file. In this last application, it has the same effect as:

    SAVE "program name", TEXT

                5-9

? MEMORY
PURPOSE

Sends information about any defined variables to an output device.

SYNTAX

[?] MEMORY

COMMENTS

This outputs the variables in memory as:

    a%=123.46
    b%=12.00
    a1$="aaaaaaaaaaaaaa bbbbbbbb"
    etc.

The variables are output in the order in which they were assigned. If you
specify OUTPUT TO file, the values of the variables can be recovered for a
subsequent program by the SET file command.

The "?" command is optional - MEMORY on its own has the same effect.

? QUERY
PURPOSE

Runs the current Query in memory and sends the results to an output device.

SYNTAX
? QUERY

COMMENTS

Query has four output options (on the Amiga, SAY provides a fifth option).
You can send the output from a Query to the screen, the printer, to disk
(as an ASCII file) or to file (as an '.sbf' file). However, when you save a
Query, the currently selected output option is not saved with the rest of
the Query settings; so if you run a Query under program control, you will
need to select the output device beforehand.

To send output to the printer, either set the Printer option from the Set
menu,  or issue a PRINT; command. To send output to disk, you should use the
OUTPUT TO filename or OPEN filename FOR OUTPUT commands.

                5-10

The Query output will then be stored on disk under file name specified.

EXAMPLES

1    LOAD QUERY "Stockrep"
    PRINT;
    ? QUERY
2    LOAD QUERY "Addreport"
    OPEN "Addrep.asc" FOR OUTPUT
    ? QUERY

NOTES

In the first example, output from the Stockrep Query is directed to the
printer; in the second example, output from the Addreport query is used to
create an ASCII file on disk under the name Addrep.asc.

? STATUS
PURPOSE
Sends information about the System Status

SYNTAX
[?]STATUS[FILE sbfname]

COMMENTS

? STATUS without the FILE option gives the same output as the menu option
System Status. If no Superbase files ('.sbf' files) are open, it displays
the following information:

    Memory free
    Diskspace Free
    Current Directory Name
    Superbase Files open (as 0)
    Superbase Files available.

If any database files are open, the header information for these files is
also shown.

    ? STATUS FILE sbfname

gives the same output as the menu option SYSTEM STATUS FILE, and

                5-11

produces a status report for the file. At the top of the report, it shows
file statistics such as the number of records and the file size. Below this,
it shows the file definition details: for each field, it lists the field
name, its attributes, format, Form View location, and any associated
calculation or validation formula.

If the file is not open, the error message 'Can't do this / File not open'
appears.

The '?' command is optional with STATUS - using STATUS on its own has the
same effect.

? TEXT
PURPOSE
Sends a text file in memory to an output device.

SYNTAX
? TEXT[MERGE]

COMMENTS

This command outputs the current text file in the Text Editor. If the text
file is a form letter and its associated database file has been opened,
adding the MERGE command will merge the data in the current record with the
text file. See also the Keyword Reference entry for MERGE.

EXAMPLES

1     OPEN FILE "Address"
      LOAD TEXT "Maillet"
    ? TEXT MERGE

NOTES

If the current output device is the screen, this example will insert the
data from the first record (in the Address file) into the Maillet text
file, and display the result in the database window.

                5-12

ABS
PURPOSE

Turns negative numbers into positive numbers but leaves positive numbers
unchanged.

SYNTAX
ABS (nexpr)

COMMENTS

ABS returns the 'absolute' value of a number. In effect, it simply strips
the sign off a negative number, making it positive. One of its common uses
is for calculating the difference between two numbers when you do not know
which is larger. In example 2, which works out the number of days between
two dates, ABS allows you to enter the dates without first knowing which is
the later date.

EXAMPLES

1    numfieldc=ABS (numfielda)
2    numfieldc=ABS (datefielda-datefieldb)
3    numfieldc>ABS (numfielda * numfieldb)
4    x%=ABS (y%)
5    x%=ABS (y% * numfielda * (datefielda-datefieldb))
6    x%=ABS (VAL (RIGHT$ (textfielda, 5)))
7    ? ABS (x%)

                5-13

ADD
PURPOSE
Adds a new field to a file definition.

SYNTAX

ADD[FILE sbfname]field-definition-string[formula-string][formula-string]

COMMENTS

This command is used in conjunction with CREATE and MAKE to create a new
Superbase database file. It cannot be used to add a field to an existing
file. To use ADD correctly, you need to understand how a file definition is
set up. The best way to do this is to use the STATUS FILE option in
Superbase's System menu. This will show you the file definition for the
current file. Another way of viewing the same information would be to list
an '.sbd' file on screen using the System menu's LIST option.

With one exception, the parameters used with ADD to define a field are the
same as those used in '.sbd' file definitions. The exception is '>' and
'>>'. These are used in '.sbd' files to indicate that there are one or two
formula lines to follow. You do not need to include these characters in a
field definition string.

From left to right, the field definition string is composed of the
following parameters:

fieldname
fieldtype[other fieldtype parameters]
format[case and multiple response parameter for text fields]
row; col

Each of these parameters must take the same form as it does in an 'sbd'
file. fieldname must conform to the rules for fieldnames. Fieldtype must be
one of the following:

TXT    text
EXT    external
NUM    numeric
DAT    date

                5-14

TIM    timefield
DEL    deleted

The other fieldtype parameters are optional and, if used, are separated
from fieldtype and each other by at least one space. You can specify up to
three of these parameters, selecting one from each of the following groups:

A)
CLC    Calculated
CLV    Calculated and validated
CON    Constant
COV    Constant and validated
VAL    Validated

B)
RDO    Read only
RDQ    Read only required
REQ    Required

C)
IXU    Indexed - Unique
IXD    Indexed - Normal

format specifies the length of a field and the numeric format for numeric
fields, format must be appropriate for the field type. For example, 20 for
TXT, z99999.00 for NUM, ddmmmyy for DAT.

The case parameter can be U, L or C, depending on whether the text data is
to shown in upper case, lower case or with the first letter capitalized.
The multiple response parameter is M followed by the number of elements in
the multiple response field (maximum 9). These parameter are optional and
can only be used with text fields. They must be separated from the field
format by at least one space. For example, to define a text field with
three multiple response fields, each up to 15 characters long, you would
enter these parameters:

    15 M3;

If you also wanted the field data to be in upper case, you would enter:

    15 UM3;

row is the row position for FORM-view (maximum 255).
col is the column position for FORM-view (maximum 255).

                5-15

row and col are optional, but you are strongly recommended to use them. If
they are not used, all the fields will be positioned at the top left of the
screen on top of one another when the record is displayed in Form View.

The field types in group A-CLC, CLV, CON, COV, VAL-must be followed by a
formula or formulas. CLV and COV require two formulas; the formula for
constants or calculations should be come first, followed by the validation
formula. Formulas should be enclosed in quotation marks and must be
separated by commas from the first part of the field definition string and
from each other.

Formula-string must follow the rules (given in Volume 1) for using formulas
for calculations, constants and validations.

Since formulas must be enclosed in quotation marks, DML will be confused if
a formula itself contains quotation marks, as in:

    fielda LIKE "[a-c]*"

The simplest solution here is to use the tilde character '~' in place of
quotation marks. When you execute the ADD command, DML will interpret the
tilde as a quotation mark.

An alternative solution is to use the CHR$ function to insert quotation
marks the ASCII code for quotation marks is 34. Thus the line to set up a
validated field called fielda of length 12 at row 5, column 20 would be:

    ADD"fielda; TXT VAL; 12, 5; 20", "fielda LIKE" + CHR$ (34)
    + "[a-c]*" + CHR$ (34)

In the unlikely event that your formula actually requires a tilde
character,  you can insert it in a string variable using CHR$ (126).

Note that the maximum length for a program line is 255 characters. Since a
formula can also be up to 255 characters long, you may be unable to enter
the entire field definition on a line. The solution is to assign formulas
to string variables beforehand. For example:

    a$="Price.Orders * Quantity.Orders"
    ADD "Subtotal; NUM; $9999999.00; 5, 20", a$

EXAMPLES

1 ADD "aatext; TXT REQ IXU; 20 M3; 1, 12"
2 ADD "aanumb; NUM; z999999.00; 1, 40"
3 ADD "bbtext; TXT CLC RD0; 10; 2, 12", "UCASE$ (LEFT$ (aatext, 10))"

                5-16

4 ADD "fielda; TXT VAL; 12; 15; 20", "fielda LIKE " + CHR$ (34) + "[a-c]*"
  + CHR$ (34)

NOTES

Creating a file under program control is a three stage process involving
CREATE, ADD, and MAKE. For a description of the process, see CREATE.

AFTER GROUP

PURPOSE
Set after group activity with reports.

SYNTAX
AFTER GROUP fieldname

COMMENTS

When you create a report using the Forms Editor's reporting facility,
Superbase generates a Report program for you. The AFTER GROUP statement is
used within a Report program to mark the start of an AFTER GROUP section.
This consists of a series of "?" statements which specify the information
that is output every time a group changes. Each statement corresponds to a
line in the AFTER GROUP box in the Forms Editor.

fieldname identifies the group and must be name of a field which has
previously been defined as a group with the GROUP statement. An AFTER GROUP
section must end with an END REPORT statement.

EXAMPLES

1     AFTER GROUP Lastname.Clients
    ? BF ?Client", GROUP, "has"; COUNT amount; "Deposits"
    ? BF "Total deposits are", @25SUM amount
    ? BF "Maximum is", @s5 MAX amount
    ? BF "Minimum is", @25 MIN amount
    END REPORT

NOTES

In the second line of this example, the keyword GROUP is used in order to

                5-17

retrieve the name of the last group. At this point, the group has already
changed; so, Lastname.Clients could not be used instead of GROUP because it
would output the name of the current group.

EXAMPLES

1    AFTER REPORT
    ?@1, 3; UL "Statistics for the Report", UL OFF: ?
    ?"Total amount is", @30 SUM amount
    ?"Number of deposits", @30 COUNT amount
    ?"Average amount", @30 MEAN amount
    END REPORT

ASC
PURPOSE
Returns the ASCII value of a single character.

SYNTAX
ASC (strexpr)

COMMENTS
ASC gives a numeric value-the ASCII code-for the text character in

                5-18

strexpr. When strexpr is longer than one character ASC returns the ASCII
code of the leftmost character of strexpr. Appendix E, Volume 1, gives the
ASCII characters and their decimal codes. The complementary function of ASC
is CHR$.

EXAMPLES

1    numfieldc=ASC (textfielda)
2    numfieldc=ASC (RIGHT$ (textfielda, 1))
3    ASC (textfielda) > 64 AND ASC (textfielda) < 91
4    x%=ASC ("A")
5    x%=ASC (x$)
6    x%=ASC (UCASE$ (MID$ (nextfield, 3, 1)))
7    ?ASC (x$)

NOTES
Example 3 provides one way of validating a text field to ensure that the
first character is uppercase (but see FCASE$).

ASK
PURPOSE
Inputs a character string from the keyboard.

SYNTAX
ASK[pos] [string] [&length]; var/field

COMMENTS

This command allows the user to enter information from the keyboard into
the computer while a program is running. It expects the user to type in one
or more characters, and, as soon as the Return key is pressed, reads them
into a variable or a field.

                5-19

string can be used to include a prompt message.

pos gives the position of the prompt text and input string. It uses the @
output format parameter to specify the column position, followed by the row
position. If pos is not given then the input string appears on the row
where the cursor is currently located.

&length limits the length of the input and shows the maximum length on
screen using an 'end-of-field' marker.

The input can be assigned to a variable or a field (in a currently open
file). If the field is not in the current file, it can be specified with
the filename extension.

var or field can be either string or numeric variables or fields, and they
must match the type of input expected: a string variable will accept
whatever you type in, but a numeric variables when you input non-numeric
data such as letters. The same restriction applies to numeric fields.

EXAMPLES

1    ASK; x$
2    ASK@2, 12"Enter a text string"; x$
3    ASK@2, 14"Enter a 3 character word"&3; x$
4    ASK"Enter data-Customer Code"&8Cuscode.custfile
5    ASK"Enter a number"; n%

ATN
PURPOSE
Calculates an angle whose tangent is known. The result is given in radians.

SYNTAX
ATN (nexpr)

                5-20

COMMENTS

This function works out the angle from the angle's tangent given in nexpr.
For example: TAN (0.7854) is 1.0, so ATN (1.00) returns 0.7854 rads (which
is 45 degrees). To convert radians to degrees multiply by PI/180.

ATN is the complementary function of TAN.

EXAMPLES

1    numfieldc=ATN (numfielda)
2    x%=ATN (y%)
3    x%=ATN (VAL (x$))
4    ?ATN (x%)

BEFORE GROUP
PURPOSE
Set before group activity with reports.

SYNTAX
BEFORE GROUP fieldname

COMMENTS

BEFORE GROUP is used in a Report Program to mark the start of a BEFORE
GROUP section.fieldname identifies the group, and must be the name of a
field which has previously been defined as a group-in the Forms Editor, you
define a group in the SELECT box; Superbase then translates this into a
GROUP statement in a Report program.

The statements in the BEFORE GROUP section ar executed every time the group
changes. Typically, they would be used to display header information for
the group data which follows.

A BEFORE GROUP section must end with an END GROUP statement.

                5-21

EXAMPLES

1    BEFORE GROUP Lastname.Clients
    ? "Deposits for client", Lastname.Clients
    ?
    ?"Firstname Lastname Bank Amount Date"
    "--------------------------------------"
    END GROUP

BELL
PURPOSE
Makes a short beep.

SYNTAX
BELL

COMMENTS

Use this command to signal that a particular process has finished and to
attract the user's attention.

With Gem versions of DML, BELL issues a tone lasting 0.5 seconds. On the
Amiga, BELL does not make a sound but causes the screen to flash.

BLANK
PURPOSE
Creates a blank record in memory.

SYNTAX
BLANK[FILE sbfname]

COMMENTS

When you want to create a new record under program control, issuing a BLANK
statement is the first step in the process. It sets up an empty record
record ready for data entry. There are several ways in which you can then
enter data into the record's fields.

Using BLANK with ENTER, allows the user to type in the data for a new
record

                5-22

from the keyboard. Together these two commands have the same effect as the
RECORD NEW option in the RECORD menu.

Alternatively, you can enter data from within a program, by assigning it
directly to the fields in the new record. Typically, this would be the
method you used to create new records by reading data in from another file
on disk.

EXAMPLES

1    BLANK
2    BLANK FILE"abc"
3    BLANK
    ENTER
    STORE
4    BLANK
    Firstname.address="John"
    Lastname.address="Smith"
    STORE

The first example creates a new record in the current file. Example 2
creates a new record in another open file. Example 3 creates a new record
in the current file, and allows the user to enter in the record; then it
saves the record on disk. Example 4 creates a new record, and enters data
into the fields Firstname and Lastname; then saves the record on disk.

BREAK
PURPOSE

Allows the user to interrupt or halt a program from the keyboard.

SYNTAX
BREAK ON/OFF

COMMENTS

BREAK ON and BREAK OFF enable and disable CTRL C. After BREAK ON (the
default condition), you can stop a program while it is running by pressing
the Control key and C at the same time. This has the same effect as
clicking on the STOP button at the bottom of the screen. CTRL C generates
error 11. If you want to include error handling routines in your programs,
you can use the ON ERROR statement to check for this error number.

                5-23

CALL
PURPOSE
Calls a user supplied function.

SYNTAX
CALL function

COMMENTS

function is string expression containing a command line to be executed by
DOS or Amiga DOS. The expression should duplicate a command line that would
normally be typed at the DOS or CLI prompt. Superbase stays in memory so
there must be enough memory for the specified command to function
correctly.

CHAIN
PURPOSE

Executes another program from within a program but does not clear the first
program's variables.

SYNTAX

CHAIN filename

COMMENTS

CHAIN allows you to carry out a task by linking together a number of
programs. When a program is running, this command loads another program
from disk, and transfers control to it. The second program displaces the
first in memory but any variables that have already been set retain their
values.

EXAMPLES

1    CHAIN "Nextprog"

                5-24

CHR$

PURPOSE
Generates the character associated with an ASCII code.

SYNTAX
CHR$ (nexpr)

COMMENTS

CHR$ works in the opposite way to ASC. Whereas ASC takes a character and
returns its ASCII code, CHR$ generates the character from its associated
code. It is useful for handling characters which are not available from the
keyboard, such as certain characters used to control a printer.

nexpr must have a positive value in the range 0-255 (although not all these
values will give printable characters). A value outside this range will
give the error 'Invalid numeric parameter'. If nexpr is not an integer, the
integer part of the number is used, i.e., 65.999 is treated as 65.

EXAMPLES

1    textfieldc=CHR$ (numfielda)
2    textfieldc=CHR$ (INT (numfielda/256))
3    x$=CHR$ (65)
4    x$=CHR$ (ASC (y$)+32)
5    FOR n%=32 to 127
    ? CHR$ (n%);
    Next

NOTES

Example 3 stores the letter A in x$. Example 4 demonstrates one way of
turning an uppercase character into lowercase - but see LCASE$ and FCASE$.
Example 5 displays the character set on the screen. Note that it does not
display characters are non-printing characters, and some of them have
unexpected effects when you attempt to display or print them.

                5-25

CLEAR
PURPOSE
Clears all user variables.

SYNTAX
CLEAR

COMMENTS

This command clears all variable assignments in memory. Using ? MEMORY
immediately after CLEAR would give no output.

CLOSE
PURPOSE

Closes an input or output channel to a text file or comms line.

SYNTAX
CLOSE INPUT/OUTPUT

COMMENTS

Only one input channel and one output channel can be open at a time, so you
are advised to use the CLOSE command when you have completed an I/O task.
Unless you close the current channel you will not be able to open a new
channel. CLOSE also ensure that all data in the disk buffer is written to
disk. If you have a large disk buffer and a small amount of data, you will
notice that some output commands-? LIST, for example-appear to have no
effect. What happens is that DML places the data in the buffer before
writing it to disk. It remains there until the buffer fills up-or until you
execute a CLOSE OUTPUT command. Associated commands are OPEN and INPUT.

                5-26

EXAMPLES

1    OPEN FILE "aaa" FOR OUTPUT
    FOR i%=1 to 10: ? i%, i%^2: NEXT i%
    CLOSE OUTPUT
    OPEN FILE "aaa" FOR INPUT
    getnext: INPUT LINE a$: ? a$
    IF EOF ("*") THEN GOTO getnext
    CLOSE INPUT

CLOSE FIELDS
PURPOSE
Closes the field list on the current file or another open file.

SYNTAX
CLOSE FIELDS[FILE sbfname]

COMMENTS

CLOSE FIELDS removes any restrictions on which fields are shown. If you
VIEW a record after issuing this command, all its fields will be displayed
on screen. On its own, CLOSE FIELDS closes the field list for the current
file. When FILE sbfname is added, it closes the list for that file.

EXAMPLES

1    CLOSE FIELDS
Close field list on current file.
2    CLOSE FIELDS FILE "abc"
Close field list for file 'abc'.

                5-27

CLOSE FILE
PURPOSE
Closes all files or a specified file.

SYNTAX
CLOSE[ALL]/[FILE sbfname]

COMMENTS

CLOSE FILE works in the same way as the equivalent option in the PROJECT
menu,  but unlike the menu option it also allows you to close all the open
files in one go.

EXAMPLES

1    CLOSE
Closes the current file.
2    CLOSE FILE "aaa"
Closes the database file 'aaa'.
3    CLOSE ALL
Closes all open database files.

CLOSE FORM
PURPOSE
Closes the current Form

SYNTAX
CLOSE FORM

COMMENTS

This command works in the same way as the Close Form option on the Project
Menu: it clears the current Form from memory and displays the current file
using one of the view modes.

                5-28

CLS
PURPOSE
Clears the screen.

SYNTAX
CLS

COMMENTS

CLS makes the output part of the screen-the output window-blank and takes
the cursor to the top left-hand corner.

EXAMPLES

1    CLS: ? "Now at top of cleared screen"

COL
PURPOSE
Returns the cursor's position across the screen.

SYNTAX
COL (0)

COMMENTS

Use this command to find out the column position of the screen cursor. For
the row position, see ROW

EXAMPLES

1    x%=COL (0)
2    ? COL (0)

NOTES

In practise, Example 2 would be pointless because the statement changes the
cursor position in the course of printing it.

                5-29

COPY
PURPOSE
Makes a copy of a file on disk.

SYNTAX
COPY from.filename[, ]/[TO]to.filename

COMMENTS

Use this command either to copy a file to the same disk under a different
name, or to copy it to another disk. In the latter case, you can give the
file the same name or a new name.

EXAMPLES

1    COPY "aaa", "bbb"
Copies 'aaa' to 'bbb'.
2    COPY "A: aaa" TO "B: bbb"
Copies 'aaa' to drive B under the name 'bbb'.

COS
PURPOSE
Returns the cosine of an angle measured in radians.

SYNTAX
COS (nexpr)

COMMENTS

To convert an angle in degrees to radians, multiply by PI/180. Associated
functions are ATN, SIN and TAN.

EXAMPLES

1    numfieldc=COS (numfielda)
2    x%=COS (y%)

                5-30

2    x%=COS (VAL (x$))
4    ? COS (x%)

CREATE
PURPOSE
Creates a new database file in memory.

SYNTAX
CREATE sbfname[: passwords]

COMMENTS

CREATE is only the first step in the process of building a new file. To
define the file and store it on disk you also need to use ADD and MAKE. The
whole process involves the following steps:

1. CREATE sbfname
2. ADD field
At this point the file is held in memory and you can check it with ? STATUS
sbfname.
3. MAKE sbfname
Writes the file to disk.

EXAMPLES

1    CREATE "Address"
    ADD "Recon; NUM CON IXU; 999999.; 0, 0", "SER (~Address~)"
    ADD "Title; TXT; 10; 1, 34"
    ADD "Firstname; TXT; 15; 3, 6"
    ADD "Lastname; TXT IXD; 20; 3, 34"
    ADD "Street; TXT; 30; 6, 6"
    ADD "City; TXT IXD; 15; 7, 6"
    ADD "Code; TXT; 12; 7, 31"
    ADD "Country; TEXT IXD; 15; 9, 6"
    MAKE "Address"

                5-31

NOTES

This example shows how to set up a simple address file under program
control. The first ADD statement defines a numeric field which is
automatically assigned a record number by means of the SER function. Note
the use of the tilde character to enter the filename Address within
quotation marks. Following this,  the ADD statements define eight text
fields which will hold the name and address. Once you have defined the file
in this way, you could then enter its data under program control, using the
commands BLANK and STORE.

CREATE INDEX
PURPOSE
Creates a new index file.

SYNTAX
CREATE INDEX ON exp[FILE sbfname][TO index][UNIQUE]

COMMENTS

This command is the program equivalent of the New Index option on the
Project menu.

EXAMPLES

1    CREATE INDEX ON aaa
2    CREATE INDEX ON aaa.bbb UNIQUE
'bbb' does not need to be the current file, but it must be open.

                5-32

DATA
PURPOSE

Holds the data (numeric and string constants) that is accessed by a READ
statement.

SYNTAX
DATA constant[, constant][, ......]

COMMENTS

The values (constants) following a DATA statement must be separated by
commas and text constants must be in quotation marks.

Because commas are used to separate the constants in a DATA statement, they
cannot be included in a constant. If you need to insert a comma in your
DATA items, you can use CHR$ (44).

To insert quotation marks in a string constant, use CHR$ (34). Date values
which are to be read into date fields must be in the correct format (e.g.,
"ddmmyy" or "mmddyy") and should be enclosed in quotation marks.

If you intend to use the RESTORE statement, you need to place a label in
front of the DATA statement.

EXAMPLES

1    DATA "abcde", 1.04, 2.46, "uvwxyz"
    data1: DATA 12.2, 12.4, 12.97, 13.4, 9.2, -1

                5-33

DATE$
PURPOSE
Returns a string from a julian date number.

SYNTAX
DATE$ (nexpr[, format-string])

COMMENTS

This function expresses a date number as a text string showing the day,
month and year. The format-string option is used to specify the date format
for the text string. It must be a valid Superbase format as shown in the
entry for DATEBASE.

If the format is given, the text string takes the date format as set with
the Date Format option on the Set menu, or as specified with the DATEBASE
command. The complementary function to DATE$ is DAYS. Associated date
functions are DAY DAYS DAY$ MONTH MONTH$ YEAR.

EXAMPLES

1    textfieldc=DATE$ (datefielda, "ddmmyy")
2    textfieldc=DATE$ (datefielda + 90)
3    textfieldc=DATE$ (TODAY)
4    x$=DATE$ (y%)
5    ? DATE$ (datefielda + 30)

NOTES

Example 3 provides a calculation to insert the system date into a
textfield. Example 2 gives the date 90 days after the date in datefielda.
The Calendar adjustment of 1752 has been accounted for.

Unless you are sure that the date supplied in nexpr will always fall within
this century, you should set the date format to allow four figures for the
year; otherwise you will not be able to distinguish between 1901 and 2001.
With dates before AD 1000, the four figure year default option does not
insert

                5-34

zeroes. AD 55, for example, is shown as 55 and not 0055. If you wish to
have four figure years-say, to line up output-add 3653048 to nexpr. As well
as ensuring that the date is always expressed as four figures, this is the
only way to access AD 0. However, early calendars were not particularly
accurate and accurate day counts between two dates cannot be relied on with
dates before AD 1400. (Superbase always gives the same answer; history,
though, is less consistent).

DATEBASE
PURPOSE
Sets the DATE format and TIME format.

SYNTAX
DATEBASE string

COMMENTS

DATEBASE allows you to specify the format with which Superbase displays the
date and time. Normally, this format only applies when you use the system
variables, TODAY and NOW. It does not affect the format of date and time
fields,  as set in the file definition. This means that if you define a
date field with the format "dd-mmm-yy", the command

    ? datefield

will display it in this format, irrespective of what the DATEBASE format
is. However, you can force Superbase to display a date field in the current
date format by enclosing the field name in parentheses, as in:

    ? (datefield)

string must have a valid date or time format, as shown in the examples
below.

EXAMPLES

1    DATEBASE "dd mmmm, yyyy"
Displays the date like this as 10 June 1987
2    DATEBASE "dd/mm/yy"
Display the date as 10/6/87

                5-35

3    DATEBASE "mm-dd-yy"
Displays the date as 6-10-87
4    DATEBASE "dd.mm.yy"
Displays the date as 6.10.87
5    DATEBASE "dd mm yy"
Displays the date as 6 10 87
6    DATEBASE "hh:mm"
Displays the time as 14:35
7    DATEBASE "hh:mm:ss"
Displays the timeas 14:35:08
8    DATEBASE "hh:mm:ss.s"
Displays the time as 14:35:08.36
9    DATEBASE "hh:mm am"
Displays the time as 2:35 pm

DAY
PURPOSE

Returns the day of the month as a numeric value from a date field or a date
string.

SYNTAX
DAY (nexpr)

COMMENTS

The number which DAY returns takes the numeric format as set in the SET-
NUMERIC FORMAT Superbase menu, or as set with the command DATEBASE.
Associated date functions are DATE$ DAY DAY$ MONTH MONTH$ YEAR.

EXAMPLES

1    numfieldc=DAY (datefielda)

                5-36

2    numfieldc=DAY (datefielda + 90)
3    numfieldc=DAY (TODAY)
4    x%=DAY (datefielda + VAL (textfielda))
5    x%=DAY (DAYS ("11 Jan 85")
6    ?DAY (datefielda + 30)

NOTES

Examples 3 provides a calculation to insert the day number of the system
date into a numeric field.

DAY$
PURPOSE
Returns the day of the week as a text string from a julian date number.

SYNTAX
DAY$ (nexpr)

COMMENTS

Associated date functions are DATE$ DAY DAY$ MONTH MONTH$ YEAR.

EXAMPLES

1    textfieldc=DAY$ (datefielda)
2    textfieldc=DAY$ (datefileda + 90)
3    textfieldc=DAY$ (TODAY)
4    x$=DAY$ (DAYS ("11 January 1985"))
5    x$=DAYS (y%)
6    ?DAYS (datefielda + 30)

                5-37

NOTES

Example 3 provides a calculation to insert the weekday of the system date
into a textfield. Example 4 provides a weekday for the date shown in
quotation marks.

DAYS
PURPOSE

Returns the date as a julian date number from a text string or text field.

SYNTAX
DAYS (strexpr) or DAYS (nexpr)

COMMENTS

This function returns a number which is the julian day number of the date
in strexpr (31 December AD 0 has a julian date value of zero). It takes the
1752 Gregorian reform of the calendar into account.

strexpr must be in a valid date format.

A text expression which is not in one of the valid date formats will
produce a message 'invalid date format'.

Associated date functions are: DATE$ DAY DAY$ MONTH MONTH$ YEAR.

EXAMPLES

1    numfieldc=DAYS (textfielda)
2    numfieldc=DAYS (datefielda + 90)
3    numfieldc=DAYS ("11 jan 85")
4    x%=DAYS (a$) + 90

NOTES

In example 2, the use of DAYS is redundant.

                5-38

DELETE
PURPOSE
Deletes a file stored on disk.

SYNTAX
DELETE filename

COMMENTS

This command has the same effect as the ERASE command in MS DOS and DELETE
in Amiga DOS. To delete a file on a drive or directory other than the
current one,  you need to place the path name in front of the file name.

EXAMPLES

1    DELETE "aaa"
2    DELETE "b: aaa"
3    DELETE "DF0: aaa"

DIM
PURPOSE
Defines array variables

SYNTAX
DIM variablename (nexpr[, nexpr][, nexpr])

COMMENTS

Arrays can have up to three dimensions. nexpr specifies the number of
elements in each dimension of an array. The maximum number of elements is
limited only by the amount of available memory.

A single DIM statement can be used to define more than one array. If DIM is
used in this way, each array definiton should be separated by commas. Note
that the first element in an array dimension has the subscript 0.

                5-39

EXAMPLES

1    DIM x% (20)
Defines a one dimensional numeric array with 21 elements.
2    DIM b$ (10)
3    DIM x% (3, 10)
4    DIM b$ (2, 12)
5    DIM a$ (20), n% (2, 3, 10), c$ (2, 10)

DIRECTORY
PURPOSE
Changes the current directory.

SYNTAX
DIRECTORY "path"

COMMENTS

Directory can be used to switch to a directory on another drive or to a
different directory in the same drive.

EXAMPLES

1    DIRECTORY "dh0: mydir/testdir"
2    x$="a: ": DIRECTORY x$
3    C: /Images

                5-40

DISKSPACE
PURPOSE
Shows the amount of space remaining on a disk.

SYNTAX
DISKSPACE (strexpr)

COMMENTS

This function gives the number of unused bytes on a disk. On the Amiga, the
disk name given in strexpr can be either a drive name or a volume name
(i.e.,  a diskname such as Mydisk: ). Gem systems only support drive names.
On the Amiga, the diskname must end in a colon. Note also that the free
block given by the CLI are 488 byte blocks.

EXAMPLES

1    Diskspace "df0:"
2    DISKSPACE ("Mydisk:")
3    x$="df1:":x%=DISKSPACE (x$)
4    ? "Remaining diskspace is: ";  DISKSPACE ("a:"); "bytes"

                5-41

EDIT
PURPOSE
Allows the user to edit a program, a text file, a Query, or an Update.

SYNTAX
EDIT [TEXT]/[QUERY]/[UPDATE]

COMMENTS

Depending on which option has been selected, EDIT displays a window or a
dialog. EDIT QUERY displays the query dialog. EDIT UPDATE displays the
update filter dialog. EDIT TEXT opens the text editor window. If none of
the three options has been selected, EDIT opens the program window. After
EDIT has opened a window or dialog, you can edit the information, just as
you would if you had selected one of the Edit options from the Superbase
menus for example, Edit Program from the Advanced menu, or Edit Query from
the Process menu. The difference is that when you exit from the window or
dialog, control returns to the program.

To exit from a window, close the window by clicking on the close gadget in
the top left-hand corner. You exit from a dialog by clicking on OK or
Cancel. In Superbase itself, clicking on OK takes the user out of the
dialog, and then runs the query or update; clicking on OK after EDIT returns
control to the program without executing a query or an update. (To run a
query, use ? QUERY, and use UPDATE to carry out an update.)

                5-42

EJECT
PURPOSE

Ejects the current page on the printer or feeds in a new page when the
number of lines remaining is less than the number specified.

SYNTAX
EJECT[nexp]

COMMENTS

EJECT on its own has the same effect as pressing the Form Feed button on
the printer. It sends a Form Feed character to the printer, which then
moves the current page on and feeds in the next. If nexp is used, the page
is ejected when the number of lines at the bottom of the page is less than
nexp.

EXAMPLES

1    EJECT
2    EJECT 3
Feeds in a new page if there are less than three lines left at the bottom
of the current page.

                5-43

END
PURPOSE
Terminates program execution.

SYNTAX
END

COMMENTS

This command brings a program to a halt and returns control to the
Superbase Menu system. END is optional and if you do not include it, DML
will return control to Superbase when it reaches the last statement in a
program.

EXAMPLES

1    IF EOF ("aaa") THEN END

END GROUP
SYNTAX
END GROUP

PURPOSE
Marks the end of a BEFORE GROUP or AFTER GROUP section.

COMMENTS

A BEFORE GROUP or AFTER GROUP section in a Report program must end with an
END GROUP statement. If it doesn't, Superbase will be unable to tell which
statements below to which section.

                5-44

END HEADING
PURPOSE
Marks the end of a HEADING section in a Report program.

SYNTAX
END HEADING

COMMENTS

A HEADING section defines the headings for a report. It must start with the
keyword HEADING, followed by one or more '?' statements which specify the
heading information. END HEADING must be placed at the end of the section.

END REPORT
PURPOSE
Marks the end of an AFTER REPORT or BEFORE REPORT section.

SYNTAX
END REPORT

COMMENTS

END REPORT must be placed at the end of the set of statements that
constitute an AFTER REPORT or BEFORE REPORT section in a Report program.
Superbase automatically generates END REPORT statements at the end of these
sections when you create a report using the Forms Editor's reporting
facility.

                5-45

ENTER
PURPOSE

Allows the user to enter data in the current file or to edit the data in a
record.

SYNTAX
ENTER[field]/[nexpr][, nexpr2]

COMMENTS

ENTER works on the current file. Used on its own, it is equivalent to the
Record menu option Edit. It displays the current record and allows you to
edit it field by field, starting with the first field. In effect, ENTER
temporarily hands over control from DML to Superbase itself. When you press
Return after the last field in a record or when you move the cursor down to
the bottom of the record,  control is transferred back to DML. If field or
nexpr is used, Superbase restricts the editing to just one field. You can
supply either a field name or a field number where the number corresponds
to the field's position in the field list; i.e., if there are six fields in
a record, the number for the first field is 1 and the number for the last
field in 6. When you enter the record, Superbase makes the editing cursor
active in the field specified and transfers control back to DML when you
press Return. With the second numeric parameter, nexpr2, you can specify
that a range of fields is available for editing, field or nexpr1 gives the
starting point, nexpr2 gives the number of fields that can be edited - from
the first field after field on nexpr1 onwards. For example, if the command
was:

    ENTER 3, 5

you would be able to edit fields 3 to 8.

You may want to specify a starting point without restricting the yourself
to a given number of fields. To do this, enter 0 as the second numeric
parameter; e.g.:

    ENTER Lastname, 3

would make the cursor active in Lastname and would allow you to edit

                5-46

Lastname and the next three fields.

ENTER works with the current view mode or Form. Note that if you have set
the Field Order on the Form, Superbase will take the first record (in the
order you have specified) as the starting point for data entry and editing.
When used in conjunction with BLANK, ENTER is equivalent to the Record menu
option New, and allows you to enter data into a new record. This command
does not save a record; to save a new or edited record use the command
STORE.

EXAMPLES

1    OPEN FILE "aaa"
    ASK "Record to edit"; x$
    SELECT KEY x$
    ENTER
    STORE
2    OPEN FILE "aaa"
    BLANK
    ENTER
    STORE
3    ENTER Lastname
4    ENTER 4, 2

Example 1 shows how to enter an existing record in order to edit it.
Example 2 creates a new record. Example 3 restricts editing to the Lastname
field. In the last example, fields 4 to 6 can be edited.

                5-47

EOF
PURPOSE

Detects the end of a database file when reading through it under program
control.

SYNTAX
EOF (strexpr)

COMMENTS

strexpr should contain the name of a currently open file. If DML reaches
the end of a file, EOF is set to -1 (true); otherwise it is set to 0
(false). EOF is only used under program control. Supplying the empty string
as an argument-EOF ("") -allows you to refer to the current file without
giving the file name. For example, to define a function key which was
equivalent to the Fast Forward button, you would enter:

    WHILE NOT EOF (""): SELECT NEXT: VIEW: WEND

EOF can also be used to detect the end of a text file. For this purpose it
takes the string "*" as an argument, and not the file name; that is, EOF
("*") is set to 'true' when the end of a text file is found. EOF is only
set and unset by the SELECT record selection commands excluding SELECT KEY
(which only set the FOUND function). In other words it is possible to
search through a file with a filter, and set EOF to 'true' by not finding a
record, and then to use the 'key-lookup' (SELECT KEY) to look for a record
outside the filter. If you do this, FOUND will reflect the success of the
'key-lookup' operation, while EOF will show that you are at the end of the
file.

EXAMPLES

1    ? EOF (x$)
    OPEN FILE "aaa"; SELECT FIRST:
    IF EOF ("aaa") THEN GOTO fempty
    loop1: SELECT NEXT: IF EOF ("aaa") THEN GOTO fend
    ....
    GOTO loop1
    fempty: ? "FILE 'aaa' has no records"; END
    fend: ? "Process completed"; END

                5-48

ERASE
PURPOSE
Clears a variable assignment from memory.

SYNTAX
ERASE varlist

COMMENTS

This command clears a variable or a list of variables from memory. If
several variables are to be cleared, varlist should contain a list of
variable names separated by commas. If you specify the name of an array,
ERASE clears all the elements in the array (it also clears any other
variable with the same name as the array).

EXAMPLES

1    ERASE x$
2    ERASE a%, b%, c%, d%, a$, b$
3    a$="Fred"
    a%=2.35
    MEMORY
    ERASE a$
    MEMORY

NOTES

The most obvious use for this command is to tidy up the variables in memory
before CHAINing another program or before OUTPUT TO "aaa" MEMORY. You could
then use SET "aaa" to pass some values to variables in the new program.

                5-49

ERR$
PURPOSE
Returns the text message associated with an error number.

SYNTAX
ERR$ (nexpr)

COMMENTS

This function returns a text string containing the error message associated
with the error number given in nexpr. Use this function in conjunction with
the control flow commands ON ERROR and RESUME, and the system variable
ERRNO.

EXAMPLES

1    ? ERR$ (ERRNO)
    CLS: NUMBASE "z9999"
    FOR i%=1 to 130
    ? "Error number"; i%, " "; ERR$ (i%)
    NEXT i%
3    x$=ERR$ (14)

Example 2 displays a list of error numbers with their associated error
messages.

ERRNO
PURPOSE
Returns the number of the last error that occurred.

SYNTAX
ERRNO

COMMENTS

ERRNO is used in conjunction with the error handling commands ON ERROR and
RESUME and with the function ERR$ which gives the error message associated
with

                5-50

an error number.

EXAMPLES

1    x%=ERRNO
2    ? ERR$ (ERRNO)

NOTES
Example 2 displays the error message associated with the last error which
occurred.

EXECUTE
PURPOSE
Executes a text string as though it were a command.

SYNTAX
EXECUTE string

COMMENTS

Any set of commands, statements, and functions that can be carried out as a
single program line can be placed in a string and then executed.

EXAMPLES

1    EXECUTE "SELECT CURRENT: VIEW: WAIT FOR 5"
    y$="REQUEST ~ OK/CANCEL Requestor ~, ~~, 1"
    EXECUTE y$

NOTES

Example 2 suggests a way of using this function to set up a user-defined
dialog which can be called from different points in a program. Note the use
of the tilde character to embed quotation marks in a string.

                5-51

EXP
PURPOSE
Returns the value of the mathematical constant 'e' raised to a power.

SYNTAX
EXP (nexpr)

COMMENTS

EXP gives the value of 'e' to the power of expr.
nexpr has a maximum absolute value of 709.7827128934, and a range of
-709.7827128934 to + 709.7827128934. This in turn gives the largest number
that Superbase can hold - 1.797693134862 times 10 to the power 308.

EXAMPLES

1    numfieldc=EXP (numfielda)
2    numfieldc=EXP (datefielda-datefield)
3    numfieldc > EXP (numfielda & numfield)
4    x%=EXP (y%)
5    x%=EXP (y% * numfielda * (datefielda-datefield))
6    x%=EXP (VAL (RIGHT$ (textfielda, 5)))
7    ? EXP (x%)

                5-52

EXPORT
PURPOSE
Exports data to an external text file from the current file.

SYNTAX
EXPORT[FILE sbfname[INDEXindex][TO]filename
[WHEREconditions] [USINGparams]

COMMENTS

This command is the program equivalent of the EXPORT option in the PROCESS
menu. It creates a text file on disk using the data from an sbf file. The
only compulsory parameter is filename, which gives the name of the text
file. If FILE sbfname is not specified, EXPORT takes data from the current
open file. Similarly, unless INDEX indexname is given, the command exports
records in the order of the current index. WHERE conditions allows you to
creates a filter to determine which records are copied to the text
file.conditions is set up in the same way as the command string in the
Filter requestor. USING parameters allows you to change the Export/Import
parameters as specified by SET-OPTIONS. These determine what characters
Superbase uses to separate fields and records in the text file. You can
also specify whether text fields are exported with or without quotation
marks around them. USING takes three parameters, each enclosed by quotation
marks and separated by commas. For example:

    USING "&", "$$", "0"

The first two parameters specify the field separation characters and the
record separation characters. As in SET-OPTIONS, you can define a separator
using one character or two characters. The third parameter must be either 0
or 1; 0 for no quotation marks,  1 to include quotation marks.

                5-53

If you want to use a non-printing character-the carriage return character
or the line feed character, for example-as a separator, you need to enter
its ASCII code with the CHR$ function. For example:

    USING "&", CHR$ (13) + CHR$ (10), "0"

defines the record separator as the carriage return character followed by
the line feed character.

EXAMPLES

1    EXPORT "aaa.exp"
2    EXPORT FILE "aaa" INDEX fielda TO "aaa.exp" WHERE
    (datefield) < DAYS ("29 Apr 87")
3    EXPORT FILE "aaa" TO "aaa.exp" USING "&", "##", "1"

                5-54

FCASE$
PURPOSE
Converts the first letter of a string to upper case, leaving the rest of
the string in lower case.

SYNTAX
FCASE$ (strexpr)

COMMENTS

FCASE$ takes a word and makes the first letter a capital letter. Associated
functions are LCASE$ and UCASE$.

EXAMPLES

1    textfielda=FCASE$ (textfielda)
2    x$=FCASE$ (y$)
3    x$=FCASE$ ("ABCDEF")
4    ? FCASE$ (x$)

                5-55

FILE
PURPOSE
Marks an open file the current file.

SYNTAX
FILE sbfnam

COMMENTS

When several files have been opened, you can use FILE to make one of them
the current file.

EXAMPLES

1    FILE "aaa"
2    x$="bbb": FILE x$
3    a$="address": b$="bank"
    OPEN FILE a$: SELECT FIRST
    OPEN FILE b$: SELECT FIRST
    PAGING OFF
    f$=b$
    lab1: VIEW: WAIT x$
    IF EOF (a$) OR EOF (b$) THEN END
    IF f$=b$ THEN f$=a$ ELSE f$=b$
    FILE f$: SELECT NEXT
    GOTO lab1

NOTES

The third example shows how you can display records from two (or more)
files at the same time. It displays one record after another, alternating
between two files until it reaches the end of the shorter file.

                5-56

FIX
PURPOSE

Sets the accuracy with which DML stores a number and performs calculations
on it.

SYNTAX
FIX (nexpr1, nexpr2)

COMMENTS

FIX allows you to limit a numeric expression to a specified number of
decimal places. nexpr2 is the number of decimal places that nexpr1 is
evaluated at. Superbase stores numeric variables at 13 figure accuracy, so
the fraction 1/3 is stored as 0.3333333333333. Adding two of these together
gives 0.6666666666667. If you set the numeric format to two decimal places
in a file definition,  Superbase would show this result as: 0.33 +
0.33=0.67. This is not incorrect, especially if you are a scientist or
engineer, but it is not very helpful if you are using a Query to produce an
invoice. FIX (1/3, 2) stores the fraction 1/3 as 0.330000000000, so FIX
(1/3, 2) + FIX (1/3, 2) gives result as 0.66. Note that numeric fields with
two decimal places are automatically FIXed.

EXAMPLES

1    numfieldc=FIX (numfielda, 3)
2    numfieldc=FIX (datefielda-datefieldb, 0)
3    numfieldc > FIX (numfielda * numfieldb, 4)
4    $x=FIX ($y, 2)
5    $x=FIX ($y * numfielda * (datefielda-datefieldb), 2)
6    $x=FIX (VAL (RIGHT$ (textfielda, 5)), 2)
7    ? FIX ($x)

                5-57

FOOTING
PURPOSE
Sets the Report footing for every page.

SYNTAX
FOOTING nexpr

COMMENTS

FOOTING is followed by a number of ? statements specifying the information
that will appear at the bottom of every page in a report. These must be
followed by an END FOOTING statement. nexpr specifies the number of lines
required for the report footing. Make sure that the number of lines output
by your ? statements is the same as the number specified by nexpr.

EXAMPLES

1    FOOTING 1
    ? "Page"; PG
    END FOOTING

NOTES
This examples uses the system variable PG to print the page number. See the
entry HEADING for more details.

FOR TO NEXT
PURPOSE
Repeats a series of program statements a specified number of times.

SYNTAX
FOR var=nexp1 TO nexp2[STEP nexp3]statements NEXT[var][, var]...

COMMENTS

This command sets up a program loop in which the statements between FOR TO
and NEXT are executed a given number of times, using var as a counter.
nexp1 sets the initial value of the counter and nexp2 sets the final value.

                5-58

If STEP nexp3 is not included, the counter is increased by one every time
the program executes the statements inside the loop; that is, every time it
passes from FOR to NEXT. When the counter reaches the value set in nexp3,
the program moves on to the next statement after NEXT. When STEP nexp3 is
included, the program increases the counter by the amount specified in
nexp3. var must be a numeric variable; nexp1, nexp2, nexp3 can be any
numeric expression,  including other numeric variables. You can use FOR TO
NEXT on the same line with multiple statements, or on multiple lines. But
if there is more than one statement between FOR and NEXT, it is advisable
to put each on a separate line. If a number of FOR NEXT loops end at the
same point, you can use a single NEXT statement for all of them.

    NEXT n%, y%, z%

is the same as

    NEXT n%
    NEXT y%
    NEXT z%

EXAMPLES

1    FOR i%=1 to 10: ? i%, i% ^ 2: NEXT
2    weekcount%=1
    FOR i%=DAYS ("01/01/87") TO DAYS ("31/03/87") STEP 7
    FOR j%=0 to 6: k%=i% + j%
    ? DAY (k%); " "; MONTH$ (k%), DAY$ (k%)
    NEXT j%
    weekcount%=weekcount% + 1
    NEXT i%

Example 2 prints out the weekdays for the first quarter of 1987 in weeks.

                5-59

FORM
PURPOSE
Specifies which part of a Form is displayed in the database window.

SYNTAX
FORM page[, row, col]

COMMENTS

This command is used to select a particular page within a multi-page form
or to bring part of a page that is outside the database window into view.
page must be a numeric expression specifying the page number.row and col
must be numeric expressions which give a row and column position within the
page. Form will then move the page so that the specified position is at the
top left-hand corner of the database window.

EXAMPLES

1    FORM 2
Selects page 2 in the Form currently displayed.
2    FORM 1, 24, 1
Makes row 24, column 1 of page 1 appear at the top left-hand corner of the
database window.

FOUND
PURPOSE
Detects whether a key lookup has been successful or not.

SYNTAX
FOUND (strexpr)

COMMENTS

After you have issued a SELECT KEY command to search for a particular
record,  FOUND will tell you whether the record has been found. If the
search is successful, FOUND returns a value of -1 (true); if the search is
unsuccessful,

                5-60

FOUND returns 0.
strexpr should contain the file name of '.sbf' file which has already been
opened. However, you can use the empty string-as in FOUND ("") -to refer to
the current file. FOUND is only set and cleared by the SELECT KEY and
LOOKUP commands.

EXAMPLES

1    SELECT KEY "London"
    ? FOUND ("")
2    a$="Clients": SELECT KEY "Smith" FILE a$
    IF FOUND (a$) THEN ? "Smith found" ELSE ? "No Smiths"

FREE
PURPOSE
Returns the amount of free memory.

SYNTAX
FREE (nexpr)

COMMENTS

This function returns a number showing how much free memory there is. On
the Amiga, nexpr determines whether the figure refers to chip, contiguous
or fast memory.

0=total free memory
2=chip memory
4=fast memory

Adding 2^17 to one of these parameters gives the largest block of memory in
its respective memory area. So, 2^17 + 2 gives the maximum area of
contiguous chip memory.

EXAMPLES

1    ? FREE (0)
2    x%=FREE (i%)

                5-61

GET
PURPOSE
Gets a character from the keyboard.

SYNTAX
GET strvar/field

COMMENTS

This command reads a character from the keyboard into a string variable or
a text field. It does not wait for a keystroke, and if no key is pressed it
returns an empty string. If you want GET to wait until a key is pressed,
you need to place it in a loop, as in:

    LABEL: GET A$: IF A$=: ""  GOTO LABEL

Alternatively, use the WAIT command.

GOSUB
PURPOSE
Calls a procedure or subroutine.

SYNTAX
GOSUB label

COMMENTS

Like the GOTO statement, GOSUB transfers control to a different part of the
program: it causes the program to branch to the label specified. But unlike
GOTO, it remembers where it branched from. When the program meets a RETURN
statement, it jumps back to the line following the GOSUB statement. GOSUB
is used to call a subroutine; that is, one or more program lines which
perform a specific task and can be called from different places within the
main program. Subroutines are useful if the same task needs to be performed
at several different stages in the program. Instead of repeating a group of
lines,  it saves space and is more convenient to put them in a subroutine.

                5-62

In DML, a subroutine is defined by a label at the beginning and a RETURN
statement at the end.

EXAMPLES

1    GOSUB sub1
2    x$=Address (1): GOSUB label1
    x$=Address (2): GOSUB label1
    .....
    .....
    .....
    label1:
    ? "This subroutine outputs x$ to the printer"
    PRINT x$
    DISPLAY;
    RETURN

GOTO
PURPOSE
Transfers control to another part of the program.

SYNTAX
GOTO label

COMMENTS

This statement makes the program jump to the label specified, instead of
continuing to the next line in the program. It alters the order in which
DML executes a program. This kind of control transfer is called an
unconditional jump. For conditional jumps, see the ON GOTO and the IF THEN
ELSE statement.

EXAMPLES

1    GOTO fred
    ....
    ....
    fred:....

                5-63

GROUP
PURPOSE

Specifies the field on which a report is grouped and the field (s) for
which subtotal reporting is required.

SYNTAX
GROUP fieldname [, fieldname] [.....]

COMMENTS

Superbase insets a GROUP statement in a report program when you specify
fields with the GROUP option on the Forms Editor's Report menu. GROUP has
two main functions. First, it defines the field on which Superbase groups
data in a report. Second, it specifies any other fields for which
subtotals-or other reporting features such as MAX and MEAN-are required. If
you wish to specify several levels of grouping, you should enter a separate
GROUP statement for each level. GROUP can also be used in an AFTER GROUP
section as a reference for the field which defines the group. Since the
group has already changed, entering the field name would output the data
for the next group; GROUP allows you to retrieve the data for the previous
group-i.e., the group for which the AFTER GROUP section provides reporting
information such as subtotals and record counts.

EXAMPLES

1    GROUP City, amount
'City' is field on which the report is grouped, 'amount' is a field for
which subtotals are required-the AFTER GROUP section may include the
statement:
    SUM amount
2    GROUP Country
    GROUP City, amount

In this example, record data is grouped at two levels: City within Country.

                5-64

HEADING
PURPOSE
Sets the Report heading for each page.

SYNTAX
HEADING

COMMENTS

Superbase generates a HEADING statement when you specify a report heading
using the Heading option on the Forms Editor's Report menu. This statement
marks the start of a HEADING section and is followed by one or more
statements which define the heading for a report. The section must end with
an END HEADING statement. If you wish to include the page number in a
heading, use the system variable PG, as in:

    ? @32, "Page"; PG

PG is set to one when the Report Select command is executed and incremented
by one after each page.

EXAMPLES

1    HEADING
    ? @22; BF; U; "DEPOSITS REPORT on", TODAY, "at", NOW; ATTR
    OFF
    END HEADING

HOME
PURPOSE
Takes the cursor to the top left-hand corner of the screen.

SYNTAX
HOME

COMMENTS

Home moves the cursor to the top of the screen without clearing the screen.
The next screen output will now appear at that position.

                5-65

HOME is useful when you want to overwrite something you have previously
displayed on screen, or when you want to move the cursor up the screen or
backwards. Normally, if you attempt to do this with LOCATE or using the @
parameter with the ? command, DML displays the next page. HOME allows you
to display text and numbers anywhere on screen, no matter what has been
displayed previously.

EXAMPLES

1    CLS
    FOR r%=1 to 18
    FOR c%=1 to 80
    HOME: LOCATE c%, r%: ? "Hello"
    NEXT
    NEXT

HRS
PURPOSE

Extracts the number of hours from a numeric expression containing the time
in thousandths of a second.

SYNTAX
HRS (nexpr)

COMMENTS

nexpr will usually be a time field or the result of a TIMEVAL expression.

EXAMPLES

1 hr%=HRS (timefield)

IF THEN ELSE
PURPOSE
Executes a statement if a condition is true.

SYNTAX
IF exp THEN statements[END IF][ELSE statements][END IF]

                5-66

COMMENTS

exp can be any expression-string, numeric or logical-which is capable of
being true or false. For example, A$="Smith" is either true or false, so:

    IF A$="Smith" THEN...

is a valid statement, but

    IF A$ THEN...

is not.

If exp is true, DML executes the statement or statements after THEN.
Otherwise it proceeds to the next statement after the IF THEN statement.
THEN can be omitted when it is followed by GOTO. For example:

    IF exp GOTO label

is the same as

    IF exp THEN GOTO label

By including the ELSE option, you can instruct DML to choose between two
courses of action. It executes the statements after THEN if exp is true; if
exp is false, it executes the statements after ELSE. An IF THEN ELSE
statement can be split up so that it is placed on several lines. If you do
this, the statements after THEN must start on a new line, and ELSE must
also start on a new line. For example:

    IF x% > y% THEN ? "Greater than" ELSE ? "Less than or equal"

can be written as:

    IF x% > y% THEN
    ? "Greater than"
    ELSE
    ? "Less than or equal"
    END IF

END IF marks the end of the IF THEN ELSE statement. It should always be
used when ELSE is placed on a separate line. If it is not used, DML assumes
that all the separate line statements in the rest of the program belong to
ELSE.

                5-67

END IF is also used when the ELSE option has not been selected, but the
statements following THEN are placed on separate lines. For example:

    IF b$="Yes" THEN n%=1: z%=2: GOSUB label

can be written:

    IF b$="Yes" THEN
    n%=1
    z%=2
    GOSUB label
    END IF
    .....
    .....

Here too, END IF is used to tell DML where the statements belonging to THEN
finish. exp does not always need to contain an operator. Remember that DML
assigns a value of 0 to false expressions and -1 to true expressions. With
IF THEN commands, though, DML treats a numeric expression with any value
other than zero as true. And it treats a numeric expression with any value
other than -1 as false.

    IF EOF ("") THEN .....

implies:

    IF EOF ("") <> 0 THEN...

Likewise,

    IF NOT EOF ("") THEN...

implies

    IF EOF ("") <> -1 THEN

EXAMPLES

1    IF exp THEN x%=x% + 1
    IF exp THEN x$="TRUE"
    IF exp THEN x%=x% + 1: x$="TRUE"
    IF exp THEN labltrue
    IF exp THEN GOTO labltrue
2    IF exp THEN x$="TRUE" ELSE x$="FALSE"
    IF exp THEN x$="TRUE": x% + 1 ELSE x$="FALSE"
    IF exp THEN labltrue ELSE lablfalse

                5-68

    IF exp THEN GOTO labltrue ELSE GOTO lablfalse
3    IF b$=MID$ (a$, 3, 1)THEN
    x%=1
    GOSUB label1
    ELSE
    x%=2
    GOSUB label2
    END IF
4    IF a$="Y" or a$="y" THEN
    ? "Yes"
    ELSE
    IF a$="N" or a$'"n" THEN
    ? "No"
    ELSE
    ? "Other"
    END IF

NOTES

Example 4 shows how IF THEN statements can be nested. In this case, the
second IF THEN statement is only executed if the condition in the first
statement gives a false result.

IMPORT
PURPOSE
Imports an external text file into an open file.

SYNTAX
IMPORT filename [TO FILEsbname] [WHERE conditions] [USING parameters]

COMMENTS

This command imports the ASCII text file specified by filename into the
current file or into the file specified by sbfname. It works in the same
way the IMPORT option in the PROCESS menu. IFTOFILE sbfname is not
specified, the text file is imported into the current open file. If it is
specified, sbfname must be an open file.

                5-69

WHERE conditions allows you to add a filter to the command.conditions is
set up in the same way as the command string in the Filter dialog. USING
parameters can be used to change the default parameters specified by
SET-OPTIONS. For a description of USING and the parameters it takes, see
EXPORT.

EXAMPLES

1    IMPORT "aaa.exp"
2    IMPORT "aaa.exp" TO FILE "aaa" WHERE (datefield) > DAYS ("29 Apr 87")

INDEX
PURPOSE
Selects the index to be used with the current file.

SYNTAX
INDEX index

COMMENTS

Superbase automatically selects the first index as default when you open a
file or when you make an open file the current file. With the INDEX
command, you can select another of the file's indexes. index is the name of
a field in the current file. An index for this field must already exist.
Because DML parses entire lines before executing them, you cannot place an
Index statement-or any other statement that refers to a field-on the same
line as the OPEN FILE statement. When the DML interpreter reaches the INDEX
statement, the file will not yet be open, and the field name, therefore,
will not be recognized. As a result, a line like

    OPEN FILE "aaa": INDEX anum

will produce an error message such as "Can't do this" or "Can't find this
field".

EXAMPLES

1    OPEN FILE "aaa"
    INDEX anum

                5-70

2    OPEN FILE "aaa": OPEN FILE "bbb"
    .....
    .....
    FILE "aaa": INDEX anum
    .....
    FILE "bbb": INDEX datea

INPUT
PURPOSE

Reads characters or a line from a text file on disk into a variable or a
field.

SYNTAX
INPUT[&nexp[, ]/LINE]var/field

COMMENTS

This statement inputs data from a text file on disk or from another
computer using the COMMS link. It assumes that an input channel has been
opened for example, by OPEN FOR INPUT. With the LINE option, INPUT reads
data from the input channel until it finds a line feed character (ASCII 10)
and inputs the data into var or field. If the line feed character has been
used as the record separator, INPUT LINE reads a record at a time. var can
be a string or numeric variable and field can be a text, numeric or date
field. However, in each case the type of variable or field used should
match the type of data expected. Thus if you attempt to input alphabetic
characters into a numeric variable they will be valued at zero, while
inputting them into a date field will produce an invalid date error. &nexp
specifies the number of characters that the command takes from the text
file. The comma after nexp is entirely optional. When nexp is zero or when
& nexp is not used, the command reads characters from the text file until
it finds a comma (ASCII 44) or a line feed character  (ASCII 10). This
option allows INPUT to be used instead of IMPORT to read in data from an
exported file. To detect the end of a text file, use EOF ("*").

                5-71

EXAMPLES

1    INPUT LINE a$
2    INPUT &6a$ (or INPUT &6, a$)
3    INPUT a%
4    FILE "aaa": EXPORT TO "aaa.exp"
    OPEN "aaa.exp" FOR INPUT
    FOR i%=1 TO RECCOUNT ("aaa")
    BLANK
    INPUT field1
    INPUT field2
    ........
    INPUT lastfield
    STORE
    NEXT i%: CLOSE INPUT

Example 4 demonstrates how INPUT can be used as an alternative to IMPORT.

INSTR
PURPOSE

Returns the starting character position of a substring within a string, or
returns 0 if the substring is not contained within the string.

SYNTAX
INSTR[nexpr, ]strexpr, substrexpr)

COMMENTS

This function returns the position in strexpr of the first occurrence of
substrexpr. If nexpr is used, INSTR searches for the first occurrence of
substrexpr from position nexpr onwards. If the substring is not found, the
value returned is zero. nexpr must be positive and less than the length of
strexpr. INSTR is case sensitive, i.e., "abc" and "ABC" are different.

                5-72

EXAMPLES

1    x%=INSTR (x$, y$)
2    x%=INSTR (textfield, "Mr")
3    x%=INSTR (x$, "Mr"): y%=INSTR (x% + 1, x$, "Mr")
4    ? LEFT$ (textfield, INSTR (textfield, " ") -1)
5    x$=LCASE$ (textfield): x%=INSTR (x$, "abc")
    IF x% > 0 THEN ? LEFT$ (textfield, x% -1)

NOTES

The second example simply locates the title 'Mr.'. Example 3 locates any
'Mr and Mrs' or 'Mr & Mrs'. Example 4 displays the first word in textfield.
Example 5 finds any occurrence of the sequence "abc" in textfield
regardless of what case the letters are in.

                5-73

INT
PURPOSE

Removes the part of a number to the right of the decimal point, turning it
into a whole number.

SYNTAX
INT (nexpr)

COMMENTS

INT does not round a decimal number up or down to the nearest whole number,
but simply strips off the decimal part. Thus INT (123.00001) and INT
(123.999999) give the same result -123.0.

EXAMPLES

1    numfieldc=INT (numfielda)
2    numfieldc=INT (numfielda * (1 + numfield) /100
3    $x=INT (VAL (RIGHT$ (textfield, 2)) /3.33
4    $x=INT ($y)
5    ? INT ($x ^ Sy)

                5-74

KEY
PURPOSE

Displays the current set of function key definitions, or defines a new set.

SYNTAX
KEY keynum[, string]

COMMENTS

For the GEM versions of Superbase Professional running under MS DOS, the
available function keys are F1 to F10. Each of these can be used with
SHIFT,  CONTROL OR ALT, giving 40 function keys in all. The numbers
associated with the keys are:

    F1-F10            1-10
    SHIFT (F1-F10)        11-20
    CONTROL (F1-F10)        21-30
    ALT (F1-F10)        31-40

On the AMIGA and the Atari ST, 21 function keys are available: the keys F1
to F10, which can be used with SHIFT, and the HELP key (HELP and Shift HELP
are the same). Their numbers are:

    F1 to F10        1-10
    SHIFT (F1-F10)        11-20
    HELP            0

string can be any set of Superbase commands which can be entered on one
line (provided that they do not access a field on the same line as an OPEN
FILE). The command line in string is assigned to the key specified by
keynum Using KEY without a following command string clears the key
associated with keynum. If keynum and string and not used, KEY displays the
current set of function key definitions.

EXAMPLES

1    KEY 1
2    KEY 1, "OPEN FILE ~aaa~: BLANK: ENTER: STORE: ? ~ Now
    ~; RECCOUNT (~aaa~); ~Records~"

                5-75

3    KEY
4    KEY 3, "Tel. [phone] [(04203) 5601 evenings]"

Example 1 clears key F1. Example 2 sets F3 to enter a record into a file
and report how many records there now are. Note the use of the tilde
character to insert quotation marks. Since the entire string must be
enclosed in quotation marks, you cannot use quotation marks within the
string.

                5-76

LABELS
PURPOSE
Prints records as labels.

SYNTAX
LABELS [FILE sbfname] [WHERE conditions] [USING labelparams]

COMMENTS

This command is the program equivalent of selecting the Labels option from
the PROCESS menu. It allows you print out records as labels and to define
their format. WHERE conditions limits the records for which labels are
printed and acts as a filter. USING allows you to specify the shape and
content of the labels to be printed. labelparams is a series of parameters
separated by commas, relating to the label definition dialog. Reading down
the left column of the dialog and then down the right column, they are as
follows:

    line 1 fields/line
    line 2 fields/line
    line 3 fields/line
    line 4 fields/line
    line 5 fields/line
    line 6 fields/line
    line 7 fields/line
    line 8 fields/line
    line 9 fields/line
    line 10 fields/line
    First label margin
    label text width
    Second label margin
    First line next label
    Copies per label
    Labels per line

Note: All 16 parameters must be used.

If USING is not specified, LABELS takes the default parameters as shown in
the label definition dialog (see Volume 1, Chapter 5).

                5-77

EXAMPLES

1    LABELS WHERE CITY="London"
    USING 1, 0, 2, 1, 1, 1, 1, 1, 0, 0, 1, 35, 40, 12, 1, 2
2    LABELS "Address" WHERE Lastname LIKE "[a-c}*"

LCASE$
PURPOSE
Converts a text string to lowercase.

SYNTAX
LCASE$ (strexpr)

COMMENTS

This function changes upper case letters to lower case; no other characters,
 including those already in lowercase, are affected. The complementary
function of LCASE$ is UCASE$.

EXAMPLES

1    textfieldc=LCASE$ (textfielda)
2    x$=LCASE$ (y$)
3    x$=LCASE$ ("ABCDEF")
4    ? LCASE$ (x$)

LEFT$
PURPOSE

Extracts one or more characters from a string, starting at the left of the
string.

SYNTAX
LEFT$ (strexpr, nexpr)

                5-78

COMMENTS

LEFT$ returns the leftmost nexpr characters of the string strexpr. Thus, if
strexpr is DICTIONARY and expr is 7:

    LEFT$ ("DIRECTIONARY", 7)

returns DICTION.

EXAMPLES

1    textfieldc=LEFT$ (textfielda, 10)
2    textfieldc=UCASE$ (LEFT$ (textfielda, 1))
    + MID$ (testfielda, 2)
3    LEFT$ (textfielda, 1) LIKE [a-c]
4    x$=LEFT$ ("ABCD", 2)
5    x$=LEFT$ (x$, n$)
6    ? LEFT$ (x$, 10)
7    strip: IF LEFT$ (x$, 1) =" " THEN x$=MID$ (x$, 2): GOTO strip

NOTES

Example 7 is a one line program to strip leading spaces from x$ (see
LTRIM$).

                5-79

LEN
PURPOSE
Returns the number of characters in a text string or text field.

SYNTAX
LEN (strexpr)

COMMENTS

LEN counts the number of characters in a string, including spaces and non-
printing characters.

EXAMPLES

1    numfieldc=LEN (textfielda)
2    textfieldc=RIGHT$ (textfielda, LEN (testfieldb)
3    LEN (textfielda) > 25 AND LEN (textfielda) 50
4    x$=LEN ("A")
5    x$=LEN (x$)
6    x$=LEN (MID$ (extfield, 3))
7    ? LEN (x$)

LET
PURPOSE
Assign a value to a variable.

SYNTAX
[LET] var/field=expr/[expr1 ? expra: exprb]

COMMENTS

The keyword LET is optional and is usually omitted. In other words, to
assign a value to a variable or a field, you only need to use the equal
sign.

                5-80

The LET option has been included in DML to maintain compatibility with
earlier versions of Basic. DML also provides a more unusual facility when
you use the syntax:

var/field=expr1 ? expra: exprab

This option provides a short way of assigning different values to a
variable or field, depending on whether an expression is true or not; that
is, it makes assignment conditional on the truth or falsity of a specified
expression. If expr1 is true, expra is assigned to the variable or field; if
it is false, exprb is assigned. It is equivalent to

    IF expr1
    THEN var/field=expra
    ELSE var/field=exprab

Used in this way, the question mark character is referred to as a 'ternary
operator' to reflect the fact that three operands are required at the right
of the equal sign. In fact, you can chain ternary operators together to
create a statement which contains multiple conditions and assigns one of
multiple values. Within a program, however, you will generally find it
easier to use the IF THEN ELSE statement. The main application for the
ternary operator is in a Superbase file definition. Here it has an
important advantage over the IF THEN ELSE statement: it can be entered as a
calculation formula for a field in a file definition. For a fuller
discussion of the ternary operator and its applications, see Chapter 2,
Volume 1.

EXAMPLES

1    item$="Sprocket"
2    Textfielda="London"
3    b%=3.25
4    numfieldb=INT (277/62)

The following examples assume that x$="ABC" and x%=4.5
5    y$= (x$="ABC") ? "yes": "no"
This example assigns "yes" to y$.

                5-81

6    y$= (x$="aaa") ? x$: ""
Assigns "" to y$.
7    y$= (x% > 3.5) ? "yes": "no"
Assigns "yes" to y$
8    y$=EOF ("INPUT") ? "end of file": "more to read"

LIST
PURPOSE
Lists a text file to the screen.

SYNTAX
LIST filename

COMMENTS

LIST is the program equivalent of the LIST option in the SYSTEM menu. It
displays a text file on the screen. Do not confuse LIST with ? LIST, which
displays a program listing. LIST only works with text files. Note also that
unlike many other DML commands, LIST requires the file name itself plus its
extension name.

EXAMPLES

1    LIST "aaa.exp"
2    LIST "Address.sbd"

                5-82

LOAD
PURPOSE
Loads any of the following types of file into memory: programs, text files,
function key files, Query and Update files.

SYNTAX
LOAD [TEXT]/[KEY]/[QUERY]/[UPDATE]filename[, APPEND]

COMMENTS

If none of the options TEXT, KEY, QUERY or UPDATE is used, Superbase
assumes that filename refers to a '.sbp' file and attempts to load a
PROGRAM file. The APPEND option can be used with program files and text
files to append a file on disk to the file in memory. Note that LOAD cannot
be used to load a Superbase data file (a file with an '.sbf' extension).
For this you need to use the OPEN FILE command.

EXAMPLES

1    LOAD "Program1"
2    LOAD TEXT "Banklet"
3    LOAD QUERY "Deptran"
4    LOAD KEY "Funkey1"
5    LOAD TEXT "Document2", APPEND

                5-83

LOCATE
PURPOSE

Sets the position at which the next output appears on the current output
device (generally, the screen or the printer).

SYNTAX
LOCATE column[, row]

COMMENTS

When you are displaying something on the screen, LOCATE allows you to
specify where it appears. column and row must be numeric expressions.row is
optional and if it is not included, LOCATE moves the cursor to the
specified column position on the current line. You cannot use LOCATE to
move the cursor backwards or up the screen: it will not move the cursor to
a position on the same line which is to the left of the current
position; and it will not move the cursor to a line above the current
position. However, you can bypass this restriction if you place the HOME
statement in front of LOCATE-see HOME.

EXAMPLES

1    LOCATE 12, 5: ? "Hello"
2    c%=12: r%=1: LOCATE c%, r%
3    LOCATE 12: ? "Hello"

NOTES

The first example displays the word 'hello' at the 12th column on the sixth
row. Example 3 displays 'hello' at the 12th column of whatever line the
cursor happens to be on.

                5-84

LOG
PURPOSE
Returns the natural logarithm (log to the base 'e') of a number.

SYNTAX
LOG (nexpr)

COMMENTS

The value of nexpr must be positive. Negative numbers or zero produce the
error message 'Invalid numeric parameter'.

EXAMPLES

1    numfieldc=LOG (numfielda)
2    numfieldc=LOG (datefielda-datefieldb)
3    numfieldc > LOG (numfielda * numfieldb)
4    x%=LOG (y%)
5    x%=LOG (y% * numfielda * (datefielda-datefieldb))

LOOKUP
PURPOSE
Detects whether an expression occurs in a file in a specified field.

SYNTAX
LOOKUP (expr, field.file)

COMMENTS

This function checks whether a given field in a file contains the
expression in expr. That is, it answers the question: does expr exist in
field.file? If it finds the expression, LOOKUP returns the value -1 (true);
otherwise it returns the value 0 (false). expr and field.file must be of
the same type (i.e. text or numeric). field.file must be the name of an
indexed field in an open file.

                5-85

LOOKUP plays a major role in cross-file validation and calculation. The
file specified with LOOKUP can be any open file; so you can use this
function to perform a relational lookup, where it checks whether the
contents of a field in one file match the contents of a field in another
file. If LOOKUP is successful-if it finds the expression you have
specified-the record containing the expression becomes the current record,
even though the file may not be the current file and is not displayed on
screen. At the same time, the FOUND function is set to -1 to reflect the
fact that the search has been successful. For a fuller explanation of
LOOKUP, see Chapter 2, Volume 1.

EXAMPLES

1    OPEN FILE "aaa": OPEN FILE "bbb"
    SELECT FIRST
    WHILE NOT EOF ("bbb")
    IF LOOKUP (field1.bbb, field1.aaa) THEN GOSUB Process_module
    WEND
    ? "Process completed": END
    Process_module:
    ......
    ......
    RETURN

This example demonstrates a small program to process only those records in
file 'bbb' that have a matching record in file 'aaa'. File 'bbb' could be
an invoice file 'joined' to a customer file 'aaa' by a customer code
(field1 in 'bbb' and 'aaa').

                5-86

LTRIM$
PURPOSE
Trims leading spaces from a text expression or a text field.

SYNTAX
LTRIM$ (strexpr)

COMMENTS

LTRIM$ returns a string consisting of the original string specified by
strexpr with any leading spaces removed.

EXAMPLES

1    textfieldc=LTRIM$ (textfielda)
2    x$=LTRIM$ (textfieldc.filea)
3    ? LEN (x$); LEN (LTRIM$ (x$))

                5-87

MAKE
PURPOSE
Stores the file definition for a file it has been defined by CREATE and
ADD.

SYNTAX
MAKE sbfname

COMMENTS

This command is used as the last step in the process of creating a new
file. After the file has been defined by CREATE and ADD, MAKE writes the
new file definition to disk together with any indexes that have created.
Note that a file definition is not regarded as valid until the MAKE command
has been executed. Before then, any error will have the effect of removing
the file definition.

EXAMPLES

1    CREATE "Address"
    ADD "Firstname; TXT REQ; 20; 1, 2"
    ADD "Lastname; TXT REQ IXD; 20; 1, 33"
    ADD "Street"; TXT; 25; 3, 2"
    (other field definitions)
    ........
    ........
    MAKE "Address"

                5-88

MENU
PURPOSE
Sets up a user-define menu

SYNTAX
MENU column, item, state[, strexpr]

COMMENTS

Superbase let you define up to 10 menu each of which can have a maximum of
12 items. With the Menu command you supply the text for a single item and
specify whether it will appear on the menu an enabled, disabled (ghosted)
or with a check mark against it. Having defined a menu with a series of
MENU commands-one for each menu item and one for the menu title-you can
then use the MENU ON command to turn the menu (or menus) on. You also use
MENU to specify a numeric variable which will return a value showing which
item, if any, has been selected. column must be a numeric expression with a
value in the range 1 to 10 giving the column number for the menu. To set up
a menu in the first column on the left at the same position as the
Superbase Project menu, you would enter a value of one. item must be a
numeric expression with a value in the range 0 to 12, giving the number of
the menu item. Item 0 is the menu heading, the text that appears on the
menu bar. state can take a value of 0, 1 or 2.0 disables the item so that
it appears on the menu as a ghosted option.1 enables it, 2 places a check
mark against it. strexpr supplies the text for the item. For example, if
you wished to define a menu in the first column which contained the option
Deposits, you could enter:

    MENU 1, 3, 1, "Deposits"

This would make Deposits the third item in the menu list. To disable the
Deposits option, you would enter:

    MENU 1, 3, 0

Note that you do not need to specify the text a second time.

                5-89

EXAMPLES

1    MENU 1, 0, 1, "Transactions"
    MENU 1, 1, 1, "Deposits"
    MENU 1, 2, 1, "Withdrawal"
    MENU 1, 3, 1, "Direct debit"
    MENU 1, 4, 1, "Standing orders"
    MENU 1, 5, 1, "Credit card"
    MENU ON a%, b%

NOTES

This example defines a menu in the first column with five options (items),
all of them enabled. (The heading for the menu is Transactions.) MENU ON
then turns the menu on. When the user selects an item, Superbase will place
its column and item numbers in the variables a% and b%.

MENU CLEAR
PURPOSE
Turns off all user-defined menus and clears their definitions from memory.

SYNTAX
MEMORY CLEAR

COMMENTS

If you want to define a new set of menus, you can use this command to clear
any menus which have been defined previously. You may also use it when your
menus are no longer required, in order to make the memory space they occupy
available for other purposes.

                5-90

MENU ON
PURPOSE
Turns user-defined menus on and specifies the variables which return the
result of a menu selection.

SYNTAX
MENU ON nvar1, nvar2

COMMENTS

MENU ON turns on any menus which have been defined with the MENU command
and sets nvar1 and nvar2 to zero. When the user selects an item, Superbase
places the column number in nvar1 and places the item number in nvar2. It
also turns all the user-defined menus off. For example, if the second item
in the third user-defined menu has been selected, the first numeric
variable specified with MENU ON, will contain the value 3 and the second
numeric variable will contain the value 2. You may sometimes want to turn
the menus off without waiting for an item to be selected. You can do this
with the command MENU OFF.

EXAMPLES

1    menuloop:
    MENU ON a%, b%
    ON a% GOSUB sub1, sub2, sub3, sub4, sub5
    GOTO menuloop

NOTES

This examples presumes that five menus have been defined and that sub1 to
sub5 are subroutines which handle item selection for each menu.

                5-91

MERGE
PURPOSE
Loads a text file and performs a mail merge.

SYNTAX
MERGE [TEXT filename] [WHERE conditions]

COMMENTS

This command merges the data in an '.sbf' file with a form letter in the
Text Editor and outputs the results to the printer. It takes data from the
current open file and-if WHERE is not included-prints one letter for each
record in the file. You can use WHERE to set up a filter restricting the
merge operation to only those records which match the conditions specified.
The TEXT option lets you specify a text file on disk; Superbase will then
load the file into the Text Editor before starting the merge operation.
Although Merge is the program equivalent of the Mail Merge option on the
Process menu, it does not allow you to preview letters on screen before
printing them. To do this, use ? TEXT with the MERGE parameter.

EXAMPLES

1    OPEN FILE "Address"
    MERGE TEXT "Mailshot1" WHERE Country LIKE "USA"

MID$
PURPOSE
Returns one or more characters from within a text string or text field.

SYNTAX
MID$ (strexpr, nexpr1[, nexpr2])

COMMENTS

MID$ is more flexible than LEFT$ and RIGHT$ as it can extract characters
from any point in a string.strexpr holds the string, and nexpr1 gives the
starting point in the string.nexpr2 specifies the length of the substring
to be extracted; if nexpr2 is not given, MID$ takes all the characters from
the starting point to the end.

                5-92

EXAMPLES

1    textfieldc=MID$ (textfielda, 10, 10)
2    textfieldc=LCASE$ (MID$ (textfielda, 8))
3    MID$ (textfielda, 12, 1) LIKE[a-c]
4    x$-MID$ (textfieldc, 19, 2)
5    x$= (x$, 4)
6    ? MID$ (x$, 4, 2)
7    ASK;A$:
    I%=LEN (A$)
    FOR n%=I% TO 1 STEP -1
    B$=B$ + MID$ (A$, n%, 1)
    NEXT
    ? B$

NOTES

Example 7 inputs a word into A$ and turns it back to front.

                5-93

MINS
PURPOSE

Extracts the number of minutes from a numeric value which holds the time in
thousandths of a second.

SYNTAX
MINS (nexpr)

COMMENTS

Usually, nexpr will be a timefield or the result of a TIMEVAL calculation.

EXAMPLES

1    mnts%=MINS (timefield)
2    ? MINS (NOW - start%); "minutes have elapsed"

MOD
PURPOSE
Gives the remainder of a numeric expression after it has been divided.

SYNTAX
nexpr1 MOD nexpr2

COMMENTS

nexpr1 is the number to be divided, nexpr2 is the number that divides into
it (the divisor). MOD returns the remainder when nexpr1 has been divided by
nexpr2. For example:

    14 MOD 3

gives 2 as a result. It is equivalent to:

    14-INT (14/3) * 3

EXAMPLES

1    ? (2.53 * 100) MOD 100

                5-94

NOTES

The example line strips off the integer part of a number and displays the
first two figures after the decimal place.

MODIFY
PURPOSE
Modifies a field definition.

SYNTAX
MODIFY field[, ] [field definition string] [, formula] [, formula]

COMMENTS

MODIFY is the program equivalent of the EDIT FILE option in PROJECT. It
allows you to alter a field's parameters; for example, the field name or its
length. The field definition and formula strings take the same form as they
do with the ADD command.

EXAMPLES

1    MODIFY Forename "Firstname; TXT REQ IXU; 15 U; 1, 12"

                5-95

MONTH$
PURPOSE
Takes a julian date number and returns the month of the year as a text
string.

SYNTAX
MONTH$ (nexpr)

COMMENTS

The same limitations on which julian dates are acceptable apply to this
function as they do to other date functions. The format of the text string
is the full month name regardless of what current date format is - i.e.,
January, not Jan). Associated date functions are DAY DAYS DAY$ MONTH MONTH$
YEAR.

EXAMPLES

1    textfieldc=MONTHS$ (datefielda)
2    textfieldc=MONTH$ (datefielda + 90)
3    textfieldc=MONTH$ (TODAY)
4    x$=MONTH$ (datefielda + VAL (textfielda))
5    x$=MONTH$ (DAYS  ("11 Jan 85")
6    ? MONTH$ (datefielda + 30)

                5-97

NEW
PURPOSE
Clears the program area or text area.

SYNTAX
NEW [TEXT/QUERY/UPDATE]

COMMENTS

On its own, NEW erases any program that is currently in the computer's
memory. When followed by TEXT, it clears the current text editor area of
memory. Following it by or QUERY or UPDATE, clears their respective
dialogs. Unlike the menu options Program New (and Text New) this command
does not put you into the program (or text) editor.

NEWLINE
PURPOSE
Sends a new line character (or characters) to an output device.

SYNTAX
NEWLINE[nexp]

COMMENTS

This command prints a new line at the current output device; i.e. with the
screen display, it takes the cursor onto the start of the next line.nexp
can be used to specify more than one new line. If nexp is not an integer,
only the integer part will be taken.

EXAMPLES

1    NEWLINE 2
2    FOR i%=1 to 20
    ? i%: if i% MOD 5=0 THEN NEWLINE i%/5
    NEXT i%

                5-98

NOTES

Example 2 outputs the numbers 1 to 5 with single line spacing, 6 to 10 with
double spacing, and so on up to 20.

NOW
PURPOSE
Gives the system time.

SYNTAX
NOW

COMMENTS

NOW shows the time of day in hours and minutes, using the current time
format. If you have a real-time clock in your computer or you have set the
system time,  this will be the current time. Note that NOW actually holds
the time in thousandths of a second. When you display the time, Superbase
automatically translates it into hours and minutes.

EXAMPLES

1    ? NOW
2    ? MINS (NOW)
3    timefield=NOW

                5-99

NUMBASE
PURPOSE
Sets the numeric format in which numbers are displayed.

SYNTAX
NUMBASE string

COMMENTS

NUMBASE is the program equivalent of the Number Format option in the SET
menu. string must be one of Superbase's valid numeric formats, as listed
Chapter 2,  Volume 1. For example, "z99999.00" or "z (+$, 000000.00".

EXAMPLES

1    NUMBASE "z99999."
Integer only format.
2    NUMBASE "+*****.00"
Numbers displayed with a sign and leading cheque-protect.

ON ERROR
PURPOSE
Tells DML to branch to another part of the program when an error occurs.

SYNTAX
ON ERROR [[GOTO] label]

COMMENTS

Normally, DML halts program execution and displays an error message when it
detects an error. ON ERROR enables error trapping, and prevents the program
from halting. Once an error has been detected, it causes the program to
jump to the error handling routine specified with label. You can use ERRNO
in your error handling routine to check on which error has occurred, and
take appropriate action. In many cases, you will want the program to resume
execution after detecting an error. You can do this with the RESUME
statement.

                5-100

To disable error trapping, use ON ERROR without a following label.

EXAMPLES

1    ON ERROR GOTO check
    ......
    ......
    ......
    check: IF ERRNO 11 THEN
    RESUME
    ELSE? "Are you sure you want to exit from this program?"
    ? "Press Y to exit, any another key to resume"
    WAIT a$
    IF a$="Y" OR a$="y" THEN END ELSE RESUME
    ENDIF

NOTES

In this example, ON ERROR is used to check whether the Stop button has been
clicked on or CTRL C has been pressed. Both these events generate error
number 11, so the error handling routine (which starts at label 'check')
first tests for this error number. If it finds that another error event has
occurred, program execution is resumed at the line which caused the error.
The error handling routine then asks if the user wishes to exit or not.
Depending on the answer it receives, it either resumes execution at the
line which caused the error (the line being executed when the user pressed
STOP or CTRL C) or terminates the program.

                5-101

ON GOSUB
PURPOSE
Calls one of a number of subroutines from a list of subroutines.

SYNTAX
ON nexp GOSUB label1 [, label2, label3, ...]

COMMENTS

This statement transfers program control to one of the subroutines given in
the list. The value of nexp determines which subroutine the program jumps
to. If nexp has valued at 1 the program branches to the subroutine at the
first label,  if nexp has a value of 2, it branches to the subroutine at
the second label, and so on. Once the program has branched to a subroutine,
it executes each statement in turn until it meets a RETURN statement. Then
it jumps back to the line following the ON GOSUB statement. Any label can
be repeated. If nexp is 0 or greater than the number of supplied labels,
program control drops to the next statement after the ON GOSUB statement.

EXAMPLES

1    ON x% GOSUB lab1, lab2, lab3
2    ON x% GOSUB lab1, lab2, lab1, lab2, lab1

ON GOTO
PURPOSE
Branches to one of a list of labels.

SYNTAX
ON nexp GOTO label [, label, ....]

COMMENTS

This command transfers program control to one of the program lines given in
the list. The value of nexp determines which label the program jumps to.

                5-102

If nexp has valued at 1 the program branches to the first label, if nexp
has a value of 2, it branches to the second label, and so on. For a general
description of GOTO refer to GOTO itself. nexp should be a positive integer.
If it is not an integer, the whole number part will be taken. Any label can
be repeated. If nexp is 0 or greater than the number of supplied labels,
program control drops to the next statement after ON GOTO.

EXAMPLES

1    ON x% GOTO lab1, lab2, lab3
2    ON x% GOTO lab1, lab2, lab1, lab2, lab1
    ? "Reached here only when x% is 0 or greater than 5

OPEN
PURPOSE
Opens a text file on disk or Comms channel for input/output.

SYNTAX
OPEN filename FOR[INPUT/OUTPUT/APPEND]

COMMENTS

When used for output to a file, OPEN has the same effect as OUTPUT TO file.
There is only one channel for INPUT, and one for OUTPUT, so you cannot have
two output channels, or two input channels. However, you can have one of
each open at the same time. APPEND is an output channel and specifies that
file is to be appended to. You must not try to specify OPEN "aaa" FOR
OUTPUT APPEND. If using OPEN, file is overwritten without warning. If using
APPEND, file need not exist. If using INPUT, file must exist.

                5-103

EXAMPLES

1    OPEN "aaa" FOR OUTPUT
2    OPEN "aaa" FOR APPEND
3    OPEN "bbb" FOR INPUT: OPEN "aaa" APPEND
    lab1: INPUT LINE a$: ? a$
    IF NOT EOF  ("*") THEN GOTO lab1
    CLOSE INPUT: CLOSE OUTPUT

NOTES

Example 3 appends the contents of file 'bbb' to file 'aaa'. Notice that the
last line of the program CLOSEs the files that OPEN has opened. This
practise is strongly recommended: you should always close a file when you
have finished writing to it.

OPEN FORM
PURPOSE
Loads a form from disk and displays it in the database window.

SYNTAX
OPEN FORM form

COMMENTS

form must be a string expression giving the file name of a form. Superbase
will also open any database files associated with the form.

EXAMPLES

1    OPEN FORM "Invoice"

OPEN FIELDS
PURPOSE
Specifies which fields are displayed.

SYNTAX
OPEN FIELDS [FILE sbfname] fieldlist

                5-104

COMMENTS

This command is the program equivalent of the Open Fields option on the
Project Menu. fieldlist consists of the list of fields required to be open.
To remove any restrictions on which fields are shown, use the CLOSE FIELDS
command.

EXAMPLES

1    OPEN FIELDS FILE "Address" Firstname, Lastname, Country, City

OPEN FILE
PURPOSE
Opens a database file and its default index.

SYNTAX
OPEN FILE sbfname [; password]

COMMENTS

Note the distinction between OPEN FILE "aaa" which opens a database file,
and OPEN "aaa" (FOR INPUT) which opens a text file. sbfname is compulsory,
and if a password is required to access the file, then it is also
compulsory (use a semicolon to separate the filename from the password).
INDEX followed by a field name may be added to the end of an OPEN FILE
command,  allowing you to select an index other than the default index. But
it can only be used if the file has already been opened by a direct command
or an earlier program line. As explained in the entry for the INDEX
command, DML parses the whole line before executing it; so if you refer to a
field, it must be a field in a file that already been opened. Otherwise an
error will result.

EXAMPLES

1    OPEN FILE "aaa"
2    x$="bbb": OPEN FILE x$

                5-105

3     OPEN FILE "aaa"; "John"

NOTES
In example 3, 'John' is the password for the file 'aaa'.

ORDER
PURPOSE
Sets the order for Query output.

SYNTAX
ORDER [&nexpr]field[ASCENDING/DESCENDING] [, field]
                ASCENDING/DESCENDING] [, .....]

COMMENTS

ORDER is a Query Language command and can only be entered in a query
section - i.e., it works in conjunction with the Query Language command
Select. This command is the program equivalent of the Order command line in
the query definition dialog: it takes the same syntax and serves the same
purpose. The field specified with the ORDER command determines the order in
which the field in the SELECT line are output. If you are familiar with the
concept of sorting,  you can think of ORDER as setting the sort 'key' for
query output. field must be a field in an open file, but it does not need
to be an indexed field; nor does it have to be one of the fields in the
SELECT line. ASCENDING and DESCENDING allow you to specify whether data is
sorted in ascending or descending order. If you specify a text field with
the ORDER command - i.e., if you specify it as the sort key-Superbase
outputs record data according to the alphabetical order of the sort field.
DESCENDING reverses the order and sorts the field from Z to A. With
numeric, date and time fields, ASCENDING sorts data in numeric, date or
time order; and DESCENDING reverses the order. By default, fields are sorted
in ascending order; so it not strictly necessary to include the ASCENDING
parameter. You can also specify more than one field in the ORDER line,
separating each with a comma. If enter two fields, the first field takes
precedence as a sort key

                5-106

over the second field; i.e., records are first sorted according to the first
field, and then any duplicate data items are sorted according to the second
key. The same applies if there are more than two fields: the second key has
priority over the third, the third has over the fourth, and so on.

EXAMPLES

The examples illustrate how ORDER works by taking a limited set of records
and showing some of the different ways in which they may be sorted. Each
record contains data from three fields, Firstname, Lastname, and Country.

1    SELECT Firstname, Lastname, Country
    ORDER Lastname

This examples takes Lastname as the sort key and produces the following
output:

FIRSTNAME        LASTNAME        COUNTRY
Pierre            Arnauld            France
William            Carter            USA
Gerde            Hemrich            West Germany
John            Miles            England
Anne            Richardson        USA
Peter            Smith            England
Robert            Brown            England

2    SELECT Firstname, Lastname, Country
    ORDER Country
The output from this query would be as follows:

FIRSTNAME        LASTNAME        COUNTRY
Robert            Brown            England
John            Miles            England
Peter            Smith            England
Pierre            Arnauld            France
William            Carter            USA
Anne            Richardson        USA
Gerde            Hemrich            West Germany

                5-107

3    SELECT Firstname, Lastname
    ORDER Country DESCENDING, Lastname ASCENDING
The output from this query is:

FIRSTNAME        LASTNAME
Gerde            Hemrich
William            Carter
Anne            Richardson
Pierre            Arnauld
Robert            Brown
John            Miles
Peter            Smith

4    SELECT Firstname, Lastname, Country
    ORDER Country, Firstname

This example uses Country as the primary sort key and Firstname as the
secondary key to produce the following output:

FIRSTNAME        LASTNAME        COUNTRY
John            Miles            England
Peter            Smith            England
Robert            Brown            England
Pierre            Arnauld            France
Anne            Richardson        USA
William            Carter            USA
Gerde            Hemrich            West Germany

NOTES

The default length for sorting is 15 characters per field. Superbase gives
equal weighing to upper case, lower case and accented instances of
characters. The & character followed by a value up to the length of the
field may precede any field, specifying the number of characters that will
be used in sorting.

                5-108

OUTPUT TO
PURPOSE
Opens a text file on disk for output.

SYNTAX
OUTPUT TO filename

COMMENTS

This command makes the disk the current output device and sends any future
output to filename. It has the same effect as OPEN filename FOR OUTPUT. If
the text file already exists on disk, any output command issued after
OUTPUT TO, will overwrite the file. If you want to add data to an existing
text file,  use OPEN filename FOR APPEND.

EXAMPLES

1    OUTPUT TO "Names"
    ? Lastname
    CLOSE OUTPUT
2    OUTPUT TO a$

NOTES Example 1 stores the contents of the Lastname field (in the current
record) on disk in the text file Names.

                5-109

PASSWORD
PURPOSE
Sets new password (or none) for a specified file.

SYNTAX
PASSWORD sbfname [; passwords]

COMMENTS

sbfname must be an open file and, as usual with filenames, must be included
in quotation marks. If no password is given, the existing password for the
specified file is removed.

EXAMPLES

1    OPEN FILE "aaa; John"
    PASSWORD "aaa"
Removes passwords.
2    PASSWORD "aaa; Rosebud"
Sets a password for the file 'aaa'.
3    OPEN FILE "aaa; John"
    PASSWORD "aaa; John; Paul; George"
Adds passwords for read/write and read only access privileges.

PCOL
PURPOSE

Return the column position of the print head on the current output printer
or resets the print head's position.

SYNTAX
PCOL (nexpr)

COMMENTS

If nexpr is zero, the function returns the column position of the print
head

                5-110

on the current printer. For the Row position, see PROW. See also LOCATE.
You can also use this function to set the counter Superbase uses to keep
track of the print head's position. Giving nexpr a positive value, sets the
counter to that value. The print head itself is not moved. This feature is
used to reset the internal count after issuing a series of printer commands
which have not in fact moved the print head, for example, after switching
to high density graphics mode.

EXAMPLES

1    x%=PCOL (0)
2    ? PCOL (0)

POSITION
PURPOSE
Sets the data pointer to a new position in an ASCII file.

SYNTAX
POSITION nexp

COMMENTS

When you read data from an ASCII file on disk, Superbase uses an internal
pointer to keep track of it. The OPEN file FOR INPUT command sets the
pointer to zero, the position of the first character in the file.
Thereafter it is incremented by one for each character that is input using
the INPUT command. POSITION sets the pointer to the character position
specified by nexpr. Normally, the data in an ASCII file is read into the
computer sequentially. With Position, you can input character data on a
more selective basis. You will only be able to take advantage of this
command if you know where the data is stored in a file. Superbase stores
data in variable length fields (as opposed to fixed length fields): when
you create an ASCII file from an '.sbf' file by exporting it, the amount of
space occupied on disk by field data may vary from record to record. This
means that there is no simple way of knowing the position of any particular
field or record. One solution to this problem is to create an ASCII file
from a database file using the query option Output to Disk. When you do
this, Superbase stores

                5-111

the data in fixed length fields-each field takes the length set in the file
definition. You can then work out the number of characters occupied by a
record in the ASCII and use this figure to retrieve specific records or
fields. For example, if the record length was 49 characters, you would
enter:

    POSITION 49 * 5 + 1: INPUT LINE a$

to retrieve the fifth record in the file (you need to add one because the first
character position is zero).

EXAMPLES

1    OPEN "Cust.asc" FOR INPUT
    FOR n%=0 to 76 * 12 STEP 77
    POSITION n%
    INPUT & 15, a$
    ? a$
    NEXT
    CLOSE INPUT

NOTES

This example inputs the first field from the first twelve records in the
ASCII file Cust.asc. It assumes that the record length is 77 characters and
that the length of the first field is 15 characters.

PRINT
PURPOSE
Sends information to the printer.

SYNTAX
PRINT[expressionlist]

COMMENT

PRINT, followed by a semicolon and nothing else, selects the printer as the
current output device. The ? command can then be used to send information
to the printer. You can also use PRINT to output information directly to
the printer, by following the command with one or more expressions. But
note that any use of PRINT makes the printer the current output device. The
items in the expression list following the Print command may be separated
by a semicolon or a comma. If a semicolon is used, Superbase will print the

                5-112

expressions one after the another without any spaces in between; a comma has
the effect of inserting a space between items. In some circumstances, you
may also dispense with separators altogether. Thus, provided it can
distinguish between different items, Superbase will accept a list of
expressions which are entered on the line head to tail; for example:

    PRINT a$b$c%"Hello"

EXAMPLES

1    PRINT;
    ? MEMORY
    DISPLAY;
2    PRINT BF "The items in the following list will be printed in bold
                  face"
    PRINT "One", "Two", "Three"; CHR$ (12)
    DISPLAY;

NOTES

The first example prints the current program's variables and their
contents. Example 2 prints a list of items, and then sends the form feed
character - CHR$ (12) -to the printer. Both examples use the DISPLAY
command to make the screen the current output device after the print
operation is finished.

                5-113

PROTECT
PURPOSE
Saves the current program in an encrypted form.

SYNTAX
PROTECT filename

COMMENTS

Use this command to ensure that program files are not seen by anyone else.
It stores a file on disk in an encrypted (scrambled) form so that it can be
run but not edited. If the first line of a program is a REM statement,
PROTECT displays that line,  but hides the rest of the program from any
attempt to edit or LIST it.

EXAMPLES

1    PROTECT "myprog"

PROW
PURPOSE
Returns the row position of the print head on the current output printer.

SYNTAX
PROW (nexpr)

COMMENTS

If nexpr is zero, the function returns the row position of the print head
on the current printer. For the Column position, see PCOL. See also LOCATE.
Giving nexpr a positive value resets Superbase's internal row counter. See
PCOL.

EXAMPLES

1    x%=PROW (0)
2    ? PROW (0)

                5-114

QUIT
PURPOSE
Exits from Superbase.

SYNTAX
QUIT

COMMENTS

This has same effect as selecting the Quit option from the Project menu. It
exits from Superbase and returns the user to the desktop interface.

                5-115

READ
PURPOSE
Reads the data given in a DATA statement and assigns it to a variable or
field.

SYNTAX
READ var/field[, var/field] [, .....]

COMMENT

The types of variables or fields used with a READ command must match the
types of data expected-numeric variables or numeric fields for numeric data
and string variables or string fields for string data. DML uses a pointer
to keep track of where it is in the list of DATA items; that is, each time a
data item is read, DML moves the pointer on to the next item in the list.
If you wish to read the same data again, you can place a label in front of
a DATA statement and use RESTORE.

EXAMPLES

1    READ a%, b$, fielda.filea, fielda.fileb

RECCOUNT
PURPOSE
Counts the number of records in a file.

SYNTAX
RECCOUNT (sbfname)

COMMENTS

This function returns a number showing how many records there are in the
file specified. You can use the empty string as an argument-RECCOUNT ("")
-to refer to the current file.

EXAMPLES

1    ? RECCOUNT ("Orders")

                5-116

2    x%=RECCOUNT (x$)
3    OPEN FILE ("address")
    SELECT FIRST
    FOR n%=1 to RECCOUNT ("address")
    VIEW
    SELECT NEXT
    NEXT n%

NOTES
Example 3 displays all the records in the file "address" in turn.

REM
PURPOSE
Inserts a non-executable comment (a remark) into a program.

SYNTAX
REM[text]

COMMENTS

REM has the effect of cancelling any statements after it. This makes it
useful when you are testing a program-placing it at the start of a
multi-statement line puts the following statements temporarily out of
action. More generally,  use REM to annotate a program in order to explain
how it works or what it does. A single quotation mark after a command
without an intervening colon also acts as a REM statement.

EXAMPLES

1    REM this is a remark
2    ....: FILE "aaa" open aaa
3    ....: FILE "aaa": REM open aaa
4    FILE "aaa": REM eliminate next commands: INDEX abc: SELECT
    FIRST

                5-117

NOTES

Examples 2 and 3 have identical effects and demonstrate the two different
ways of entering a comment. In example 4, the REM statement means that the
INDEX and SELECT FIRST commands are not executed.

REMOVE FILE
PURPOSE
Removes a database file from disk, along with its associated definition and
index files.

SYNTAX
REMOVE sbfname

COMMENT

This command operates in the same way as the Remove File menu option. Note
that you are not asked for confirmation-the file is just removed.

EXAMPLES

1    REMOVE FILE "aaa"
2    REMOVE FILE "DF1: aaa"
3    REMOVE FILE "GEM\SBASE\aaa"

REMOVE FROM
PURPOSE
Removes records which match the conditions specified.

SYNTAX
REMOVE FROM FILE sbfname[WHERE conditions]

COMMENTS

This command works in the same way as the equivalent PROJECT-REMOVE-FILE
menu option. It deletes records from a file on disk.

                5-118

FILE sbfname has to be open, and if the file requires a password, you must
have full access to it.

WHERE conditions is optional and is set up in the same way as a filter. If
it is not included, the command acts on all the records in a file.

EXAMPLES

1    REMOVE FROM FILE "aaa" WHERE Lastname LIKE "[a-c]*"
2    REMOVE FROM FILE "aaa"
This empties the file of all its data.

REMOVE INDEX
PURPOSE
Removes an index on the current file from disk.

SYNTAX
REMOVE INDEX index

COMMENT

This command works in the same way as the Remove Index option on the
Project menu. The file must be open, and, if it requires a password, you
must have full access privileges. index is the name of an indexed field. It
can be entered with a file extension.

EXAMPLES

1    REMOVE fielda
2    REMOVE fieldb.aaa

                5-119

RENAME
PURPOSE
Renames a file on disk.

SYNTAX
RENAME old.filename[, /TO]new.filename

COMMENT

This command works in the same way as the RENAME command in MS DOS or Amiga
DOS, but allows you to rename a file without exiting from Superbase. You
have the option of using either a comma or the keyword TO as the separator
between the two file names.

EXAMPLES

1    RENAME "aaa", "bbb"
2    RENAME "aaa" TO "bbb"

REORGANIZE
PURPOSE
Reorganizes the current file or a specified file.

SYNTAX
REORGANIZE [FILE sbfname] [TO]sbfnameb

COMMENTS

This command is the program equivalent of the Reorganize option on the
System menu (see Chapter 8, Volume 1). It takes a file on disk, reorganizes
it, and stores it as sbfnameb. IF the FILE option is not used, the current
file is reorganized. sbfnameb can include the pathname for another
directory or disk. If you enter a pathname without a file name following
it, the file will be reorganized under the same name.

                5-120

Note that you cannot reorganize a file under the same name in the same
directory; i.e. if a pathname is not supplied, sbfnameb must not be the same
as sbfnamea.

EXAMPLES

1    FILE "aaa": REORGANIZE TO "copy"
2    REORGANIZE "aaa" TO "a: mydir\"
3    REORGANIZE "aaa" TO "DF1: Mydir/"
Example 1 creates a reorganized file 'copy' in the current directory,
Example 2 creates a reorganized file 'aaa' in directory mydir on the disk
in drive a (or,  in example 3, drive DF1 on the Amiga).

REPLICATE
PURPOSE
Replicates a character a given number of times.

SYNTAX
REPLICATE (strexp, nexp)

COMMENTS

REPLICATE repeats the character in strexpr the number of times given in
nexp.

EXAMPLES

1    textfieldc=REPLICATE ("*", 10)
2    x$=REPLICATE (textfieldc, 4)
3    x$=REPLICATE (MID$ (x$, 4, 2), 6)
4    x$=REPLICATE  (" ", 25)

NOTES
Example 4 fills x$ with 25 spaces, but see function SPACE$.

                5-121

REPORT
PURPOSE
Specifies the field or fields on which totals (and other report statistics)
will be produced for the report as a whole.

SYNTAX
REPORT [SUMMARIZE] [params]fieldname[, fieldname][, ....]

COMMENT

Report has two uses. When you create a Report with the Forms Editor,
Superbase generates a Report statement by noting the fields which have been
specified in an AFTER REPORT section; i.e., if the AFTER REPORT section in a
Report program contains the statements:

    ? SUM amount
    ? COUNT deposits

Superbase will generate the following line in the program:

    REPORT amount, deposits

If you are writing a Report program yourself (as opposed to modifying a
program generated by Superbase), you should remember to enter a Report
statement including the names of any fields for which you wish totals and
other report statistics to appear. The second application for REPORT is a
query language command. In this context,  it allows you to create a program
line which is equivalent to the REPORT command line in the query definition
dialog. REPORT is used here to specify the fields for which totals and
other statistical. When you use the SUMMARIZE option, Superbase suppresses
the main detail of the report and prints just the summary information.

                5-122

REQUEST
PURPOSE
Displays a Superbase dialog.

SYNTAX
REQUEST text1, text2, type[, nvar[, strvar[, len]]]

COMMENT

REQUEST allows you to select one of Superbase's dialogs and display it on
screen. To some extent you can also customize a dialog to your own
requirements. Thus you can place a title in box, and you can specify the
text string that initially appears in the dialog's command line or
selection box. For certain dialogs, it also possible to specify the length
of the box. text 1 and text2 are the first and second line of the dialog
title. They must be included although they can be "". The maximum length
for each line is 50 characters. type is the dialog type. It defines the
type of dialog according to the table shown below. nvar is a numeric
variable. It returns a value of 1 if OK is selected and there is an entry
into the string dialog. If CANCEL is selected or there is no entry into the
string dialog, it returns 0. strvar can be used with dialogs which have a
string entry box and has two functions: It is used to place a default value
into the string box, i.e., the text string in strvar is entered into the
string box when the dialog is displayed. It returns the string which the
user enters in the box. len specifies the length of the string box (where
appropriate). This is particularly useful for the information dialogs. For
dialog types 5-16 it is not need as Superbase sets the box to the maximum
file name length of 50 characters. For dialog type 4 len must be specified.

                5-123

Types of Dialogs available:

TYPE    DIALOG            BUTTONS
0    string            OK
1    string            OK CANCEL
2    string            OK
3    string            OK CANCEL
4    string            OK CLEAR CANCEL
5    Database Files        OK CLEAR CANCEL
6    Open Fields List    OK CLEAR CANCEL
7    Indexed fields        OK CLEAR CANCEL
8    Non indexed fields    OK CLEAR CANCEL
9    Field Info        OK CLEAR CANCEL
10    Open Database Files    OK CLEAR CANCEL
11    Database Files        OK CLEAR CANCEL
12    Program Files        OK CLEAR CANCEL
13    Text Files        OK CLEAR CANCEL
14    Query Files        OK CLEAR CANCEL
15    Update Files        OK CLEAR CANCEL
16    Function Key Files    OK CLEAR CANCEL
17    Directory listing    OK CLEAR CANCEL
18    Subdirectory List    OK CLEAR CANCEL

Note that a database file must be open before dialogs 5 to 9 can be
selected.

EXAMPLES

1    REQUEST "", "", 2,
2    a%=0:a$="":REM initialize nvar and strvar
    REQUEST "Select a program", "", 5, a%, a$, 32
    IF a%=0 THEN ? "OK so you do not want to run a program":END
    CHAIN a$
3    a%=0:a$=":OPEN FILE "aaa"
    REQUEST "Select an Index", "", 7, a%, a$
    IF a%=0 THEN END
    INDEX a$
    lablook:a$="":REQUEST "Enter a key", "", 1, a%, a$, 15
    IF a%=0 THEN END
    SELECT KEY a$
    IF FOUND  ("aaa") THEN GOTO lablook2
    REQUEST "No Record with key" + a$, "See Nearest ?", 1a%

                5-124

    IF a%=0 THEN GOTO lablook
    lablook2:VIEW:WAIT FOR 5:GOTO lablook

NOTES

Example 1 puts an "OK" dialog up for 2 seconds. Example 2 allows the user
to select a program to run. Example 3 in essence duplicates the key lookup
function from the ? button on the Superbase Control Panel. Note the
concatenation of the first title line of the dialog on the third from last
line.

RESTORE
PURPOSE
Moves the data pointer back to the first DATA statement, or to a specified
label.

SYNTAX
RESTORE[label]

COMMENTS

The data pointer is the internal pointer that Superbase uses to keep track
of which DATA statements have been read. Initially it has a value of zero
and points to the first DATA statement. As you READ data into variables or
fields,  the data pointer is increased by one for every data item read.
This command resets the data pointer. If you do not specify label, the data
pointer is reset to the beginning of the first DATA statement. If you
specify label, the data pointer is reset to the data statement following
the label.

EXAMPLES

1    RESTORE
2    RESTORE datalabel1

                5-125

RESUME
PURPOSE
Resumes execution after an error.

SYNTAX
RESUME[NEXT/label]

COMMENTS

The RESUME command works in conjunction with the ON ERROR GOTO command
which is used to trap program errors. RESUME, on its own, returns program
control to the statement that caused the error. When NEXT is included, the
statement returns program control to the statement after the one which
caused the error. label transfers program control to the label specified.

EXAMPLES

1    REM Top of program
    ON ERROR GOTO errlab1
    SELECT FIRST:? fieldname
    .....
    .....
    errlab1: IF ERRNO=44 THEN OPEN FILE "aaa": REM file not open
    RESUME
2    REM read data
    ON ERROR GOTO errlab2
    .....
    READ x$
    .....
    endread:.....
    .....
    .....
    errlab2: IF ERRNO=18 THEN RESUME endread: REM out of data

                5-126

RETURN
PURPOSE
Returns from a subroutine.

SYNTAX
RETURN

COMMENTS

The RETURN command is used to mark the end of a subroutine. It instructs
the computer to transfer program control to the statement immediately
following the GOSUB or ON GOSUB statement which initially called the
subroutine. See GOSUB.

RIGHT$
PURPOSE
Extracts one or more characters from a text string or text field, starting
from the right-hand end of the string.

SYNTAX
RIGHT$ (strexpr, nexpr)

COMMENTS

This function starts at the right of a string given in strexpr and extracts
nexpr characters.

EXAMPLES

1    textfieldc=RIGHT$ (textfielda, 10)
2    textfieldc=LCASE$ (RIGHT$ (textfielda, 1))
3    IF RIGHT$ (textfielda, 1) ="s" THEN....
4    x$=RIGHT$ ("ABCD", 2)
5    x$=RIGHT$ (x$, 4)

                5-127

RND
PURPOSE
Returns a random number.

SYNTAX
RND (nexpr)

COMMENTS

What the function returns depends on the value of nexpr.
It nexpr is less than zero, the random number generator is reseeded. This
means that a new series of random numbers will be generated, completely
unrelated to the last series. It also allows you to generate the same
series again for testing purposes, by entering the same seed. If nexpr is
zero, the number returned is the same as the previous one. If nexpr is
positive, a new random number is generated. The random number returned is
in the range 0 to 1. Technically, it is never zero and never unity, but all
values between 0 and one will be randomly generated and the distribution of
numbers will be relatively flat.

EXAMPLES

1    numfieldc=RND (numfielda)
2    numfieldc=RND (2) * 12
3    textfieldc=MID$ (x$, RND (2) * 6 + 1, RND (2) * 12 + 1)
4    $x=RND ($y)
5    ? RND ($x)

                5-128

ROW
PURPOSE
Returns the row position of the cursor on the screen.

SYNTAX
ROW (0)

COMMENTS

This function shows how far down the screen the cursor is. For the column
position, see COL.

EXAMPLES

1    x%=ROW (0)
2    ? ROW (0)

NOTES
In practise, example 2 would be pointless, because it changes the position
of the cursor in the course of printing it.

RUN
PURPOSE
Executes a program from memory, or loads it from disk and then runs it.

SYNTAX
RUN[filename]

COMMENTS

This will run the program currently in memory when used as a command or as
a program statement without the filename option. If filename is used to
specify a program, Superbase loads the program from disk and then runs it.
If filename is specified, it must be a string variable or a string constant
in quotation marks.

                5-129

SAVE
PURPOSE
Saves any of the following types of file: program, text, function key,
query, and update files.

SYNTAX
SAVE [TEXT/KEY/QUERY/UPDATE]filename[, TEXT]

COMMENTS

filename is required. Superbase detects files of different types as
follows:

    aaa.sbk is a saved function key set
    aaa.sbp is a saved program
    aaa.sbq is a saved query
    aaa.sbt is a saved document (text)
    aaa.sbu is a saved update

If none of the options TEXT, KEY, QUERY or UPDATE is used, Superbase
assumes that filename refers to an '.sbp' file and attempt to save a
program file. If you include TEXT as the last parameter, DML saves a
program file as a text file. Only one of the options, TEXT, KEY, QUERY or
UPDATE, can be used at a time.

SAVE FILE
PURPOSE
Saves the current file definition.

SYNTAX
SAVE FILE sbfname

COMMENTS

When you create a new file, you can use MAKE to save the file definition.
SAVE FILE, however, must be used after you have edited a file definition
with MODIFY.

                5-130

SAY
PURPOSE
Converts a text string into speech, using the Amiga's speech synthesis
facility.

SYNTAX
SAY [USING parameters]exprlist

COMMENTS

SAY is only available on the Amiga. The parameters for the USING option are
in this order:

    Pitch, Inflection, Rate (wpm), Sex, Phonemic

The following table gives the range of each parameter and its default
value:

PARAMETER    RANGE        DEFAULT        NOTES
Pitch        65-320        110
Inflection    0-1        0        0 is expressive, 1 is
                                                  monotone
Rate in wpm    40-400        150
Sex        0-10        0        0 is male, 1 is female
Phonemic    0-1        0        0 translates to phonemes,
                          1 assumes phonemes

SAY only works with string expressions. To hear an external sound field use
the SHOW command.

EXAMPLES

1    OPEN FILE "Address"
    SELECT FIRST
    WHILE NOT EOF ("Address")
    SAY Forename; Lastname; "comes from"; City; Country
    SELECT NEXT
    WEND
2    SAY USING 280, 1, 200, 1, 0"Hello there", USING 140, 1, 200, 0, 0
    "Well, hello there"

                5-131

SCRDUMP
PURPOSE
Outputs a copy of the screen to the printer-carries out a screen dump.

SYNTAX
SCRDUMP

COMMENTS

Only available on the Amiga.

SECS
PURPOSE
Returns the numbers of seconds from a time field.

SYNTAX
SECS (nexpr)

COMMENTS

nexpr will usually contain a time in milliseconds (thousandths of a second)
from a time field or from the result of a TIMEVAL calculation.

EXAMPLES

1    scnds%=SECS (timefield)
2    scnds%=SECS (TIMEVAL ("10:22AM"))

SELECT COMMANDS

The following SELECT commands relate to Record selection:

    SELECT CURRENT
    SELECT DUPLICATE
    SELECT FIRST
    SELECT KEY
    SELECT LAST
    SELECT NEXT

                5-132

    SELECT PREVIOUS
    SELECT REMOVE
    SELECT WHERE

SELECT commands can only be used on an open database file, although this
does not have to be the current file. These commands do not display records
on screen. To do this, you need to use VIEW. Similarly, although they can
be used with any open file, the SELECT commands do not automatically make
an open file the current file. For example, SELECT LAST selects the last
record in a file (on index) even if the file is not current. If the file is
current, executing the VIEW command will be enough to display the last
record. But with any other open file, you will also need to use the FILE
command (as opposed to the FILE parameter) before you can display the
record (FILE makes an open file the current file).

SELECT CURRENT
PURPOSE
Selects the current record.

SYNTAX
SELECT CURRENT [FILE sbfname] [INDEX index]

COMMENT

This command has the same effect as the Current Record button on the
Control Panel at the bottom of the screen. Use INDEX to select the current
record using a different index.

                5-133

SELECT DUPLICATE
PURPOSE
Selects the next record with the same key.

SYNTAX
SELECT DUPLICATE [INDEX index]

COMMENTS

This command finds the next record with the same key as the current key.
The key is the field on which the file is currently indexed. If SELECT
DUPLICATE fails to find a record with the same key, the EOF function is set
to true.

1    SELECT FIRST:VIEW:x%=1
    lab1:SELECT DUPLICATE
    IF NOT EOF ("aaa") THEN VIEW:x%=x% + 1:GOTO lab1
    ? "End of "; x%; "duplicates-strike key"
    lab2:SELECT PREVIOUS:SELECT NEXT:IF EOF ("aaa") THEN END
    CLS:VIEW:GOTO lab1

Example 1 displays duplicate entries on an index. In Table view, it shows a
set of records at a time.

SELECT FIRST
PURPOSE
Selects the first record in the current or specified index sequence.

SYNTAX
SELECT[FILE sbfname] [INDEX index]

COMMENTS

This command has the same effect as the First Record button on the Control
Panel. Use the INDEX parameter to alter the current index.

EXAMPLES

1    SELECT FIRST

                5-134

2    SELECT FIRST "Stock" INDEX Prodcode

NOTES

Example 1 selects the first record in the current file according to the
current index. Example 2 selects the first record in the Stock file
according to the Prodcode index.

SELECT KEY
PURPOSE
Selects the first record with matching string.

SYNTAX
SELECT KEY string [FILE sbfname] [INDEX index]

COMMENTS

This command has the same effect as the Key Lookup button on the Control
Panel. It searches the file for the first record whose index field matches
the string specified. Unlike the other SELECT commands, this command does
not affect the EOF function,  but instead sets the FOUND Function (see the
example given for FOUND).

EXAMPLES

1    SELECT KEY "Zollinger"
    VIEW
2    SELECT KEY "Johnson" FILE "Customer" INDEX Lastname
    IF FOUND ("Customer") THEN FILE "Customer":VIEW

NOTES

Example 1 selects the record in the current file whose Lastname field
contains the name Zollinger. It assumes that the current file is indexed on
Lastname. The program in example 2 selects the record in the Customer file
whose Lastname field contains the name Johnson. The Customer file must have
already been opened, but it does not have to be the current file. If the
program finds a record with a matching key, it uses the FILE command to
make the Customer file current and then displays the record.

                5-135

SELECT LAST
PURPOSE
Selects the last record in the current or specified index sequence.

SYNTAX
SELECT [FILE sbfname] [INDEX index]

COMMENTS

Has the same effect as the Last Record button on the Control Panel.

SELECT NEXT
PURPOSE
Selects the next record in the current or specified index sequence.

SYNTAX
SELECT NEXT [FILE sbfname] [INDEX index]

COMMENT

Has the same effect as the Next Record button on the Control Panel.

SELECT PREVIOUS
PURPOSE
Selects the previous record in the current or specified index sequence.

SYNTAX
[FILE sbfname] [INDEX index]

COMMENTS

This command has the same effect as the Previous button on the Control
Panel.

                5-136

SELECT REMOVE
PURPOSE
Removes the current record in the current file or another open file.

SYNTAX
SELECT [FILE sbfname]

COMMENTS

This command has the same effect as the Remove option on the Record menu.

SELECT WHERE
PURPOSE

Selects first record that matches the filter conditions or removes the
filter.

SYNTAX
SELECT WHERE[[FILE sbfname] [conditions]]

COMMENTS

This command has the same effect as the Filter button on the Control Panel.
conditions is set up in the same way as the string gadget in the Filter
requestor. If not specified, the current filter conditions are cleared.
SELECT WHERE can only be used to set a single file filter. If you enter the
name of a field which also occurs in another open file, you should include
the file the file name as an extension. Otherwise, Superbase may assume you
are attempting to use this command in a multi-file operation, and will
issue the error message:

    Can't do this
    This Where statement must be single file

If you wish to set a multi-file filter - to select records whose field data
matches the data in another file - use the LOOKUP function or the query
language command WHERE.

                5-137

EXAMPLE

1    SELECT WHERE fielda LIKE "[a-c]"
2    SELECT WHERE "Stock" fieldb LIKE "[a-c]"
3    SELECT WHERE

NOTES

Once set, the Control Panel filters remains active until it is cleared.
Example 3 clears the filter which may have been set by a previous SELECT
WHERE command or by direct entry in the filter dialog.

QUERY LANGUAGE COMMANDS

DML's Query Language commands allow you to create a program which duplicates
a Superbase query. These commands are used in report programs created by
the Forms Editor; but they can also be used for any of the query
applications described in Chapter 11, Volume 1 - sorting records, creating
complex multi-file filters, merging files, and so on. In Superbase a query
is defined by the four command lines in the query definition dialog
(Chapter 5, Volume 1, introduces this dialog; Chapter 11 explains it in more
detail). These command lines can be reproduced in a program by using the
query language commands. SELECT is used to define the Fields command line;
REPORT defines the Report command line; WHERE corresponds to the FILTER
line; and ORDER is used for the Order line. You will find a explanation of
these commands under their respective keyword entries. Here, we will
describe how they work together to form a query section. A query section
must start with the SELECT command and it should end with END SELECT. Any
other query language commands are optional; you will include them according
to your requirements. Thus, if you wish to use a filter, you will include a
WHERE command within the query section.

                5-138

Likewise, if you wish to use reporting functions such as SUM and COUNT, you
will need to insert a REPORT command after the SELECT command and before
END SELECT. You can think of REPORT, WHERE and ORDER as modifying the query
output which is specified with the SELECT command. When SELECT is used on
its own - to form a single line query section - it outputs data from each
record in a specified file (or files) in turn. For example:

    SELECT Lastname.Address, Country.Address:
    END SELECT

This outputs a line showing the contents of the fields Lastname and Country
for each of the records in the Address file. As such, SELECT works in the
same way as the ? command except that it acts on all the records in a file.
If you inserted TO PRINTER after Country.Address in the example above,
SELECT would output data to the printer. The TO device parameter provides
an equivalent to the Output options in the query definition dialog. You can
use to specify an output device other than the screen:the printer, an ASCII
file, or a new '.sbf' file.

A QUERY LANGUAGE EXAMPLE

Any query created with the query definition dialog can be reproduced under
program control. We can illustrate this by converting a query file (an
'.sbq' file) into a program, taking the Deptran file supplied with the
demonstration file disk as an example. Deptran can be displayed on screen
using the LIST option from the System menu. It looks like this:

    SB
    CLIENTS
    DEPOSITS
    Deposit Transaction Report
    ON "Clients" Firstname.Clients, Lastname.Clients, ON "Deposits"
    @24 Bank, Amount, Deposits
    REPORT SUM Amount COUNT GROUP Lastname.Clients SUM
    Amount
    Lastname.Clients=Lastname.Deposits
    Lastname.Clients

SB on the first line indicates that this is a Superbase Professional query
file as opposed to one created in Superbase Personal. The next two lines
contain the names of the database files which are associated with this
query. 'Deposit

                5-139

Transaction Report' is the query title, and the remaining lines represent
the four query command lines. Before we can load this file into the Program
Editor, we need to change its name to Deptran.sbp. To do this, select COPY
from the System menu and, after selecting Deptran.sbq as the file to be
copied, enter then name Deptran.sbp. You can now load the file into the
Program Editor using the Program open option. Converting it to a program is
just a matter of deleting two lines and inserting keywords in the others.
Once you have made these changes, the program should look like this:

    OPEN FILES "CLIENTS"
    OPEN FILE "DEPOSITS"
    SELECT ON "Clients" Firstname.Clients, Lastname.Clients, ON
    "Deposits" @24 Bank, Amount, Deposits
    REPORT SUM Amount COUNT GROUP Lastname.Clients SUM
    Amount
    WHERE Lastname.Clients=Lastname.Deposits
    ORDER Lastname.Clients

Note that the report line is the same as in the query file and does not
need to be altered. If you now run this program, it will have the same
effect as running Deptran from the query definition dialog (by clicking on
OK).

SELECT
PURPOSE
Specifies which are to be output from a query.

SYNTAX
SELECT [params]fields[TO device]:[statements]:END SELECT

COMMENTS

SELECT is a Query Language command and can used on its own or with other
Query Language commands to form a query section. fields can be one or more
field names from one or multiple files.params can be any of the output
format parameters as listed in the section which describes the ? commands.

                5-140

In addition, there are three format parameters which can only be used with
the SELECT command:ON file, AS heading and FIELD. The syntax and function
of these parameters in described in their respective sections in Chapter
11, Volume 1. TO device specifies the device to which the query output will
be sent. If it is not included output is to the screen. The device options
are:

    TO PRINTER

Outputs to the printer.

    TO FILE file

Creates a new '.sbf' file on disk under the file name specified, using the
query output.

    TO file

Outputs to the ASCII file on disk specified by file.
statements can be other query language statements formed with the commands
REPORT, WHERE, and ORDER. END SELECT is used to indicate the end of a query
section. It is not always necessary to include END SELECT, but you must
provide Superbase with some indication of where the query section finishes
and where the rest of the program starts. Otherwise, the statements
following the last line in the query section will be interpreted as part of
a multi-line SELECT statement. As an alternative to END SELECT, you could
use a blank line.

                5-141

SER
PURPOSE
Returns the total number of records that have been created in a file.

SYNTAX
SER (filename)

COMMENTS

You can use the SER function to assign a serial number to each record in a
file. To do this, you need to define a field which will hold the serial
number. It should be defined as a constant field and should have SER
("filename") as its constant formula. When you create the first record, it
will be given the value 1. This value will then be incremented by one for
each record you add to the file. The difference between SER and RECCOUNT is
that SER gives the total number of records that have been created,
irrespective of whether they have been deleted later. RECCOUNT returns the
number of records currently in the file.

1    ? SER ("Stock")
2    BLANK
    Recno.Stock=SER ("STOCK")
    Price.Stock=14.95
    Description.Stock="Widget"
    STORE

SET
PURPOSE
Reads a text file and executes any commands in the file, or assigns
variables from a text file.

SYNTAX
SET filename

COMMENTS

This command reads in a text file and executes it as if it were a sequence
of

                5-142

command. The file, therefore, must contain valid DML commands. If the file
holds a set of variables-which have previously been saved to disk by ?
MEMORY-the variable assignments are executed. This provides a way of
transferring variables between different programs when CHAIN is not
appropriate. For example, Program 'a' can set up variables for Program 'c',
but Program 'a' CHAINs to Program 'b'. Another application would be to
communicate variables between different programs which are run on different
days.

EXAMPLES

1    ......
    process a
    ......
    OPEN "aaa" FOR OUTPUT:? MEMORY:CLOSE OUTPUT:DISPLAY
    another program
    SET "aaa"
    ......
    process b
2    SET "abc"
'abc' could be ASCII file which contains a set of function key assignments.

                5-143

SET BUFFERS
PURPOSE
Sets the number of buffers Superbase uses as a disk cache.

SYNTAX
SET BUFFERS nexp

COMMENTS

Operates in the same way as the Buffers option in Set Menu Options, and
allocates 512 bytes memory space for each buffer. nexp can have a value
from 1 to 99.

EXAMPLES

1    SET BUFFERS 24

SET PAGING
PURPOSE
Sets paging on or off.

SYNTAX
SET PAGING[ON/OFF]

COMMENTS

When used without ON/OFF, it acts as toggle and operates in the same way as
the SET-PAGING menu options. With ON or OFF, it sets paging accordingly.

EXAMPLES

1    SET PAGING OFF

                5-144

SET VIEW MODE
PURPOSE
Sets the view mode or switches between one of the view modes and a Form.

SYNTAX
SET [TABLE]/[FORM]/[RECORD]

COMMENTS

Works in the same way as the equivalent Set Menu option, except that it
does not automatically display a record (use VIEW). If a Form (as opposed
to Form view) is displayed, the SET command switches the Form off and
selects the specified view mode. The Form remains in memory and can be
switched on again by repeating the SET command for the same view mode. In
other words, when a Form has been opened, the SET command toggles the
current view mode on and off.

EXAMPLES

1    SET FORM
2    SET TABLE:VIEW

SGN
PURPOSE
Finds the sign of a number.

SYNTAX
SGN (nexpr)

COMMENTS

This function returns the positive value of 1 if nexpr is positive and
returns the negative value -1 if nexpr is negative.

                5-145

EXAMPLES

1    numfieldc=SGN (numfielda)
2    IF SGN (datefielda-datefieldb) THEN GOTO lab1
3    x%=SGN (y%)
4    x%=SGN (y% * numfielda * (datefielda-datefieldb))
5    x%=SGN (VAL (RIGHT$ (textfielda, 5)))
6    ? SGN (x%)

NOTES
Example 2 tests whether datefieldb is later than datefielda

SHOW
PURPOSE
Shows an external file.

SYNTAX
SHOW [field]/[strexpr]

COMMENTS

SHOW is the program equivalent of the camera button at the bottom of the
screen. It displays a picture or text from an external file.field must be a
field which holds the name of the external file, but it does not have to be
a field in the current file:if you add a file name extension to the field
name,  you can display pictures using other open database files. As an
alternative to specifying an external field, strexpr allows you to specify
the name of an external file. When field or strexpr is not given, SHOW
removes the picture from the screen.

                5-146

SIN
PURPOSE
Returns the sine of an angle measured in radians.

SYNTAX
SIN (nexpr)

COMMENTS

This function returns the sine of the angle in nexpr, where the angle is
measured in radians. To convert degrees to radians, multiply by 180/PI.

EXAMPLES

1    numfieldc=SIN (numfielda)
2    x%=SIN (y%)
3    x%=SIN (VAL (x$))
4    ? SIN (x%)

SPACE$
PURPOSE
Fills a string with a specified number of spaces.

SYNTAX
SPACE$ (nexpr)

COMMENTS

nexpr must be in the range 0 to 255.

EXAMPLES

1    textfieldc=SPACE$ (10)
2    x$=SPACE$ (4)

                5-147

SQR
PURPOSE
Returns the square root of a number

SYNTAX
SQR (nexpr)

COMMENTS

The function returns the square root of the number specified by nexpr. If
nexpr is less than zero, the function returns the error message 'invalid
number'.

EXAMPLES

1    numfieldc=SQR (numfielda)
2    numfieldc=SQR (2 * numfielda)
3    textfieldc=STR$ (SQR (VAL (x$)))
4    x%=SQR (y%)

STORE
PURPOSE
Stores the current record in the current file or in the file specified.

SYNTAX
STORE[, 0/1/2] [FILE sbfname]

COMMENTS

This command stores the record in memory for the current file, or for the
file specified with sbfname. It is equivalent to the Save option on the
Record menu.

                5-148

The numeric parameters - 0, 1 or 2 - allow you to specify whether the
record is stored in batch mode or in the normal way (see the section on
Batch in Chapter 5, Volume 1). STORE, 1 stores the current record in batch
mode. The time taken to save the record on disk will be reduced, but the
data will not yet be secure:if you suffer a power loss, you will lose any
record data which has been saved (in the current session) using this
option. Note that STORE, 1 only turns on batch mode for the current
record.STORE, 2 does not store a record but makes the file secure. Any
records that have been saved previously with the STORE, 1 command will now
be made safe on disk. You should always execute a STORE, 2 command after
storing records in batch mode. STORE, 0 is optional and is the same as
STORE on its own:Superbase makes each record secure as it is stored. If you
were to turn the computer off accidentally, the most you would lose would
be the data in memory.

EXAMPLES

1    BLANK
    Firstname="John"
    Lastname="Roberts"
    Street="15 Richmond Way"
    ......
    ......
    ......
    STORE
2    FOR n%=1 to 10
    BLANK
    Firstname=Recdata$ (n%, 1)
    Lastname=Recadata$ (n%, 2)
    Street=Recdata$ (n%, 3)
    ......
    ......
    ......
    STORE, 1
    NEXT
    STORE, 2

                5-149

NOTES

The first example creates a new record and stores it in the normal way.
Example 2 creates ten new records, reading data into the fields for each
record from the array Recdata$ and storing them in batch mode. When all the
records have been stored, it makes the file secure with the STORE, 2
command.

STR$
PURPOSE
Returns the text equivalent of a numeric expression.

SYNTAX
STR$ (nexpr [[, nexpri [, nexprd]]/[, numeric-format-string]])

COMMENTS

STR$ converts data which is held in a numeric variable or numeric field
into a text string. nexpri specifies the number of integers before the
decimal point and should be set large enough to avoid overflow display.
nexprd specifies the number of integers after the decimal point. The
maximum numeric format in Superbase is a total of 13 integers, so nexpri
plus nexprd must be less than 14. As an alternative to using nexpri and
nexprd, you can specify the numeric format as a string (see NUMBASE). If
these parameters are not used, the default numeric format set by Numeric
Format on the Set menu or by the most recent use of NUMBASE will be taken.
The complementary function to STR$ is VAL.

EXAMPLES

1    textfieldc=STR$ (numfielda)
2    textfieldc-STR$ (numfielda, 5, 0)
3    x$=STR$ (165.4444, "z999999.00")

                5-150

TAN
PURPOSE
Returns the tangent of an angle measured in radians.

SYNTAX
TAN (nexpr)

COMMENTS

The function returns the tangent of the angle in nexpr measured in radians.
The complementary function of TAN is ATN.

EXAMPLES

1    numfieldc=TAN (numfielda)
2    x%=TAN (y%)
3    x%=TAN (VAL (x$))
4    ? TAN (x%)

THOUSECS
PURPOSE
Takes a numeric value and returns the number of thousandths of a second
left over after subtracting the number of seconds.

SYNTAX
THOUSECS (nexpr)

COMMENTS

nexpr will usually contain a time in milliseconds from a time field or the
result of a TIMEVAL calculation. THOUSECS returns the same result as nexpr
MOD 1000.

1    x%=THOUSECS (timefield)

                5-151

TIME$
PURPOSE

Returns the time in string format from a numeric value which gives the time
in thousandths of a second.

SYNTAX
TIME$ (nexpr [, timeformat])

COMMENTS

The second argument for this function, timeformat, allows you to specify
the format the time string will have. It must conform to the rules for
Superbase time formats given in the keyword entry for DATEBASE.

EXAMPLES

1    x$=TIME$ (timefield)
2    ? TIME$ (NOW, "hh:mm:ssam")

TIMEVAL
PURPOSE
Returns the value of a time string in thousandths of a second.

SYNTAX
TIMEVAL (strexpr)

COMMENTS

strexpr must contain the time in a valid time format. See the keyword entry
for DATEBASE for a list of acceptable time formats.

EXAMPLES

1    t%=TIMEVAL ("10:22am")
2    t%=TIMEVAL ("14:03:12.201")

                5-152

TODAY
PURPOSE
Gives the system date.

SYNTAX
TODAY

COMMENTS

TODAY shows the date in the date format as set with Date Format option in
the Set menu, or as set by the DATEBASE command. If your computer has a
real-time clock or you have set the system date, TODAY gives the current
date. Otherwise,  it gives the default system date. TODAY holds the date as
a julian date number. Superbase automatically translates this into the
current date format when you display the date using ? TODAY.

EXAMPLES

1    ? TODAY
2    datefield=TODAY
3    ? MONTH (TODAY)

                5-153

TRIM$
PURPOSE
Trims trailing spaces from a string or a text field.

SYNTAX
TRIM$ (strexpr)

COMMENTS

This returns the string consisting of the original string specified by
strexpr with any trailing spaces eliminated.

EXAMPLES

1    stringfieldc=TRIM$ (textfielda)
2    x$=TRIM$ (textfieldc.filea)
3    ? LEN (x$); LEN (TRIM$ (x$)

UCASE$
PURPOSE
Returns the upper case equivalent of a text string or a text field.

SYNTAX
UCASE$ (strexpr)

COMMENTS

UCASE$ returns the upper case equivalent of the lowercase alphabet; no other
characters, including those already in upper case, are affected. The
complementary function of UCASE$ is UCASE$.

EXAMPLES

1    textfieldc=UCASE$ (textfielda)
2    x$=UCASE$ (y$)

                5-154

3    x$=UCASE$ ("ABCDEF")

NOTES

If you wish to set the first letter of a string to upper case, leaving the
rest in lower case, you can so using the FCASE$ function.

UPDATE
PURPOSE
Performs a relational update.

SYNTAX
UPDATE[calclist] [WHERE conditions] [END UPDATE]

COMMENTS

UPDATE on its own runs the update in memory. This may have been loaded from
disk with the LOAD UPDATE command, or it may have been created in the same
session using the Process menu option Update Edit. By specifying calclist
and conditions, you can also use UPDATE to define an update and then run
it. calclist corresponds to command line set in the Update Fields
dialog; conditions corresponds to the filter which is set in the Update
Filter dialog. The first specifies how the records are updated, the second
specifies which records are to be updated. WHERE conditions and calclist
should be entered as separate statements, either on the same line as UPDATE
separated by colons, or on separate lines. They form part of an Update
program section, headed by the UPDATE command and ending with END UPDATE.
The END UPDATE command must be included if the Update section is followed
by other statements in a program. Otherwise Superbase will regard these as
belonging to the Update section. As an alternative to using this command,
you can terminate the section with a colon or a blank line. UPDATE is a
multi-file command, so both conditions and calclist can refer to more than
one file. In this case, the first condition in the update filter must
establish a join between two files.

                5-155

EXAMPLES

1    LOAD UPDATE "Newrate":UPDATE
Loads the Update file Newrate from disk, and then runs it.
2    UPDATE
    Price.Orders=Price.Stock
    WHERE Product_Code.Orders=Product_Code.Stock AND
    Order_date "15 July 1987"
    END UPDATE
Updates prices in the Orders file on the basis of the price details in the
Stock file.

VAL
PURPOSE
Returns the numeric value of a text string.

SYNTAX
VAL (strexpr)

COMMENTS

The function returns the numeric value of the number (if any) in the
lefthand end of the string or substring specified in strexpr. In cases
where strexpr does not contain a number or where the leftmost character of
strexpr is not numeric,  the function returns 0. The complementary function
of VAL is STR$

EXAMPLES

1    numfieldc=VAL (textfielda)
2    numfieldc=VAL (RIGHT$ (textfielda, 8))
3    VAL (textfielda) > 1 AND VAL (RIGHT$ (textfielda, 4) > 0
4    x%=VAL ("12.45A456")
5    x%=VAL (x$)

                5-156

VIEW
PURPOSE
Displays the current record in the current file.

SYNTAX
VIEW

COMMENTS

Allows the user to see the current record in the current file in the view
format specified by the SET view mode command. It can also be used to
redisplay the current Form.

WAIT
PURPOSE
Waits for a specified time or until a key is pressed.

SYNTAX
WAIT [FOR time]/[FOR nexp] [var/field]

COMMENTS

Wait waits for a given number of seconds (FOR nexp) or until a given time
(FOR time). FOR nexp implies 'wait for nexp seconds'. FOR time implies
'wait until the system clock reached time', where the time is given in the
current time format. FOR var/field implies 'wait until a key is pressed,
and then place it in var or field'. If you follow WAIT with a numeric
variable or numeric field, it will only accept a number. In other word,
pressing any key except the keys with the digits 0 to 9, will have no
effect.

                5-157

EXAMPLES

1    WAIT FOR 3
Waits for 3 seconds.
2    WAIT FOR 10:20:30
Wait until 10:20 am.
3    WAIT x$
Waits for a single key stroke and puts it in x$.

WHERE
PURPOSE
Set the filter conditions for a query or a report.

SYNTAX
WHERE conditions

COMMENTS

WHERE is the program equivalent of the Filter command line in a query
definition, and can only be used within a section that is headed by the
query SELECT command. You can use WHERE to set a filter on the fields
selected for report output or for other query applications, such as
sorting, merging files, or simply retrieving data with query that has been
saved to disk. conditions takes the same form as the Filter command line in
the query definition dialog (see Chapter 11, Volume 1). WHERE is a
multi-file filter command - unlike the record selection command SELECT
WHERE - and if it used for this purpose, the join between two files must be
placed at the beginning of the statement, as in:

    WHERE Lastname.Clients=Lastname.Deposits

Any subsidiary conditions can then be added to the line using the AND
operator.

EXAMPLES

1    SELECT Firstname.Clients, Lastname.Clients, Bank, Amount
    WHERE Lastname.Clients=Lastname.Deposits AND

                5-158

    Lastname.Clients LIKE "[d-3]*"
    ORDER Lastname.Clients
    END SELECT
2    WHERE Price > = 50 AND Price < = 100
3    WHERE Lastname LIKE ["a-c"*] AND NOT (Country=USA)

NOTES

In the first example, WHERE is used to set up a multi-file filter. It
selects only those clients whose details are also stored in the Deposits
file and whose last name initial falls in the range A to C. Note that file
extension must be given for Lastname since the field occurs in both the
Clients file and the Deposits file; the Bank and Amount fields do not
require an extension name since they only occur in the Deposits file. The
other two examples show WHERE in use as a single file filter command.

                5-159

WHILE WEND
PURPOSE
Executes a series of instructions as long as the specified conditions are
true.

SYNTAX
WHILE exp statements WEND

COMMENTS

WHILE and WEND set up a loop, in which the statement in between are
executed repeatedly for as long as the expression following WHILE is true.
When the expression is not true, execution resumes with the first statement
after WEND.

EXAMPLES

1    OPEN FILE "Address"
    SELECT FIRST
    WHILE NOT EOF ("Address")
    VIEW
    SELECT NEXT
    WEND
2    WHILE NOT EOF (*"): INPUT &1, a$:? a$:WEND

YEAR
PURPOSE
Returns a numeric value for the year from a julian date number.

SYNTAX
YEAR (nexp)

COMMENTS

The function is only valid for dates from 1 January 1 to the end of
December 9999. Consequently nexpr is only valid in the range 1 to 3652048.
If nexpr is 0 then the number returned is 0. If nexpr is negative the
results are unpredictable. Associated date functions are DATE$ DAY DAYS
DAY$ MONTH

                5-160

EXAMPLES

1    numfieldc=YEAR (datefielda)
2    numfieldc=YEAR (datefielda + 90)
3    numfieldc=YEAR (TODAY)
4    x%=YEAR (datefielda + VAL (textfielda))
5    x%=YEAR (DAYS ("11 Jan 85")
6    ? YEAR (datefielda + 30)
7    YEAR (datefielda)=1986

NOTES

Example 3 provides a calculation to insert the month number of the system
date into a numeric field. Example 7 provides a filter to pick out all the
dates in datefielda which fall in the year 1986.

                5-161

            CHAPTER 6 - QUICK REFERENCE GUIDE

APPLICATION FUNCTIONS

RUN [filename]
Execute program, optionally loading from disk

CHAIN filename
Execute program without clearing variables

NEW [TEXT/QUERY/UPDATE]
Clear program or text area

EDIT [TEXT/KEY/QUERY/UPDATE]
Allow user to edit program, text, query or update

LOAD [TEXT/KEY/QUERY/UPDATE] filename [, APPEND]
Load program, text, file, function key list, query or update

SAVE [TEXT/KEY/QUERY/UPDATE] filename [, TEXT]
Save program, text file, function key list, query or update

PROTECT [filename]
Save the current program in encrypted form

CALL function
Call a user supplied function

SYSTEM COMMANDS

DEBUG [ON/OFF]
Set or clear debug flag

BREAK [ON/OFF]
Set or clear user stop enabled

QUIT
Exit Superbase system

KEY keynum [, string]
Set keynum to string or clear it

                6-1

LIST filename
List any system file to screen

DELETE filename
Delete any system file

RENAME old filename [, TO] new filename

COPY from filename [, TO] to filename
Copy any system file

NUMBASE string
Set default numeric format

DATEBASE string
Set default date format

DIRECTORY path
Change directory to path

SET TABLE/RECORD/FORM
Set view according to parameter

SET PAGING [ON/OFF]
Set paging

SET BUFFERS nexp
Set number of cache buffers to use

BASIC STATEMENTS

[LET] var/field=exp
Assign value of expression to variable or field

ERASE varlist
Remove a variable from memory

CLEAR
Clear all system variables

READ var/field [, var/field]
Read data into variables or fields from data pointer

                6-2

DATA constant [, constant]...
Specify data for READ statement

RESTORE [label]
Move data pointer to specified position or home

REM text
Non executable comment line

EXECUTE string
Execute text string as though command

DIM array variable
Set array dimensions

CONTROL FLOW

FOR var=nexp TO nexp [STEP nexp]statements NEXT [var]
Repeat program lines a number of times

GOSUB label
Call a procedure or subroutine

GOTO label
Call a procedure or subroutine

GOTO label
Branch to the specified label

ON ERROR [GOTO label]
Specify procedure to be followed on error condition

ON nexp GOTO label [, label]...
Branch to statement or label in list

ON nexp GOSUB label [, label]...
Call procedure or subroutine in list

RETURN
Return from procedure or subroutine execution

RESUME [NEXT / label]
Resume execution after error at next or specified position

END
Terminate execution of application

                6-3

WHILE expr
Perform following commands if expression true

WEND
Mark end of while command sequence

CONDITIONALS

IF exp THEN statement/label [ELSE statement/label]
Conditional statement or expression execution

varfield=exp ? expr:expr
Conditional assignment of value to field or variable

FILE AND INDEX COMMANDS

CREATE sbfname; passwords
Create a new database file in memory

CREATE INDEX ON exp [FILE sbfname] [TO index] [UNIQUE]
Create a new index file optionally make unique

ADD [FILE sbfname] field definition string [, formula string]
Add a new field to a file

MAKE sbfname
Make the file exist on disk and store the file def

MODIFY field [, ] field definition string [, formula string]
Modify parameters for field changing name, type etc.

SAVE FILE sbfname
Save the current file definition

PASSWORD sbfname; passwords
Set new passwords for a specified file

REORGANIZE [FILE sbfname] [TO] pathname
Reorganize current or specified file to new pathname

OPEN FILE sbfname; passwords
Open file set as default

                6-4

CLOSE [ALL]/[FILE sbfname]
Close all or specified files

FILE sbfname
Select the default file to be used

INDEX index
Select the default index to be used for a file

REMOVE FILE sbfname
Remove all data, file and all indices

REMOVE INDEX index
Remove the specified index for specified file

OPEN FIELDS [FILE sbfname] fieldlist
Open a set of fields for specified file

CLOSE FIELDS [FILE sbfname]
Close the open fields for specified file

RECORD COMMANDS

BLANK [FILE sbfname]
Clear all data from current record

STORE [0/1/2, ] [FILE sbfname]
Store current record in the file, batch mode optional.

ENTER [field/nexpr] [, nexpr2]
Allow the user to enter a record in the current file

VIEW
View record in the current file

SELECT
Record selection commands

SELECT FIRST [FILE sbfname] [INDEX index]
Select the first record in key sequence

SELECT LAST [FILE sbfname] [INDEX index]
Select the last record in key sequence

                6-5

SELECT NEXT [FILE sbfname] [INDEX index]
Select the next record in key sequence

SELECT PREVIOUS [FILE sbfname] [INDEX index]
Select the previous record in key sequence

SELECT CURRENT [FILE sbfname] [INDEX index]
Select the current record in key sequence

SELECT DUPLICATE [FILE sbfname] [INDEX index]
Select the next record with the same key

SELECT REMOVE [FILE sbfname]
Remove the current record in selected file

SELECT KEY string [FILE sbfname] [INDEX index]
Select the first record with index matching string

SELECT WHERE [FILE sbfname] [conditions]
Select the first record matching conditions or clear conditions

SELECT field parms [WHERE parms] [REPORT parms] [ORDER parms]
[SAY]/[TO PRINTER/filename/FILE sbfname] [END SELECT]
Query language command

PROCESS COMMANDS

UPDATE calc list [WHERE conditions] [END UPDATE]
Perform relational update

REMOVE FROM FILE sbfname WHERE conditions
Remove records matching conditions

IMPORT filename [[TO] FILE sbfname] [WHERE conditions] [USING
parms]
Import external text file to superbase

EXPORT [FILE sbfname] [INDEX index] [TO] filename [WHERE
conditions [USING parms]
Export to external file

LABELS [FILE sbfname] [WHERE conditions] [USING labelstring]
Print labels as per label definition

                6-6

MERGE [TEXT filename [WHERE conditions]
Load text file and mail merge

INPUT OUTPUT FUNCTIONS

SHOW field/strexpr
Show external field

OPEN filename FOR INPUT/OUTPUT/APPEND/COMM
Open sequential file for input/output

POSITION nexp
Position in sequential file

INPUT [&nexp/LINE] var/field
Input characters or line from text file

CLOSE INPUT/OUTPUT/COMM
End input/output to/from text file or comms

SET filename
Read exec or variable file and execute

GET var/field
Get character from keyboard no wait

WAIT FOR time/FOR nexp/var/field
Wait till time, for no of secs or for single key entry

ASK [string] [pos] [length] ;var/field
Get input string from user

BELL
Ring bell

HOME
Move screen output position to home

CLS
Clear output screen

EJECT [nexp]
Do new pages on print device

                6-7

SCRDUMP
Do screen dump to printer

LOCATE coordinates
Set position on output device

NEWLINE [nexp]
Send newline to output device

MENU column, item, state [, text]
Set up a user defined menu

MENU CLEAR
Clear user-defined menu

MENU ON numvar
Turn on user-defined menus, specify variable for return value

REQUEST text[, ] text[, ] type [, numvar [, textvar [, len]]]
Set up a user-defined dialog (requester)

MEMORY
List of variables in memory

STATUS [FILE sbfname]
Status of selected file or system

SAY [[USING pitch, mode, rate, sex, phonemes] string [, /; string...]]
Amiga only. Output string as speech

FG nexp
Set foreground colour

BG nexp
Set background colour

UL [ON/OFF]
Set or clear underline

IT [ON/OFF]
Set or clear italics

BF [ON/OFF]
Set or clear bold face

                6-8

ATTR OFF
Clear bold face italics and underline

? /DISPLAY/PRINT/OUTPUT TO file
Send information to selected output device

? SAY
Use narrator device to speak output

? MEMORY
List of variables in memory

? LIST
Program listing in memory

? STATUS [FILE sbfname]
Status of selected file or system

? DIRECTORY
Current directory listing

? TEXT [MERGE]
Text file in memory optionally mail merging

? QUERY
Current query statement

? exprlist
Any expression list

REPORTING

HEADING statements END HEADING
Specify statements to execute on page heading

FOOTING statements END FOOTING
Specify statements to execute on page footing

REPORT total list
Set report totals, means and count

BEFORE REPORT
Specify before report activity

                6-9

AFTER REPORT
Specify after report activity

END REPORT
End of report specifications

GROUP field total list
Specify subtotal break field and subtotals, means and counts for group

BEFORE GROUP statements
Specify before group activity

AFTER GROUP statements
Specify after group activity

END GROUP
End of group specifications

FORM HANDLING

CLOSE FORM
Close current form

OPEN FORM formname
Load a form into memory

FORM [, page [, row [, column]]]]
Specify page for current and top left-hand corner

ENTER [FORM view name] [field list
Enter data into fields through view form

OPERATORS

ARITHMETIC OPERATORS

^
Exponentiation

-
Negation

                6-10

*
Multiplication

/
Division

MOD
Modulo arithmetic

+
Addition

-
Subtraction

RELATIONAL OPERATORS

=
Equality

LIKE
Pattern matching case insensitive equality

<>
Inequality

<
Less than

>
Greater than

<=
Less than or equal to

>=
Greater than or equal to

                6-11

LOGICAL OPERATORS

NOT

AND

OR

MATHEMATICAL FUNCTIONS

SGN (x)
Sign of variable

INT (x)
Integer portion of variable

ABS (x)
Absolute value of variable

SQR (x)
Square root

RND (x)
Random number

LOG (x)
Logarithm

EXP (x)
Exponent

COS (x)
Cosine

SIN (x)
Sine

TAN (x)
Tangent

ATN (x)
Arctangent

FIX (x, y)
Fix decimal precision of value

                6-12

FREE (n)
Return free memory size

DISKSPACE ("disk")
Return free disk space

RECCOUNT (sbfname)
Return number of records in file

SER (sbfname)
Return serial number of specified file

ROW (0)
Return current screen row

COL (0)
Return current screen column

PROW (n)
Return current printer row

PCOL (n)
Return current printer column

EOF (sbfname)
Return if at end of file

FOUND (sbfname)
Return result of last search

LOOKUP (value, fld)
Return if value exists in file (indexed field)

STRING FUNCTIONS

LEN (x$)
Length of string

STR$ (x[[, y] [, z] / [, numformat]])
String from number with optional format

VAL (x$)
Value of string

                6-13

ASC (x$)
Ascii value of character

CHR$ (x$)
String value of character

LEFT$ (x$, nexp)
Left portion of string

RIGHT$ (x$, nexp)
Right portion of string

MID$ (x$, nexp [, nexp])
Mid portion of string

DAYS (x$)
Numeric value of date

DATE$ (nexp [, dform])
Date string from numeric using optional format

DAY (date)
Numeric day value of date

DAY$ (date)
Day of week from date

MONTH (date)
Numeric month value of date

MONTH$ (date)
Month string from date

YEAR (date)
Numeric year value of date

TIMEVAL (time)
Numeric value of time

TIME$ (nexp [, tformat])
Time string from numeric using optional time format

HRS (time)
Number of hours from time

                6-14

MINS (time)
Number of minutes from time

SECS (time)
Number of seconds from time

THOUSECS (time)
Number of thousandths of second from time

LCASE$ (x$)
Convert string to lower case

UCASE$ (x$)
Convert string to upper case

FCASE$ (x$)
Capitalize first letter of string

TRIM$ (x$)
Trim trailing spaces from x$

LTRIM$ (x$)
Trim leading spaces from x$

INSTR ([n, ]x$, y$)
Find position of substring y$ in x$

REPLICATE (x$, nexp)
Replicate character expression n times

SPACES$ (n)
Return string with n spaces

ERR$ (n)
Returns error message for error number n

VARIABLES

TODAY
Return system date

NOW
Return system time

                6-15

ERRNO
Return current error number

PI
Return value of pi

FIELDS BY NAME
Fieldname; Field.file; Field. "file"

MULTIPLE RESPONSE FIELDS
Fieldname (nexp)

STRING VARIABLES
X$

NUMERIC VARIABLES
X%

ARRAYS
X% or X$ (nexp[[, nexp] [, nexp]])

                6-16

                   INDEX

& 5-4                        C
? 5-8                        Changing the output device
                        5-3
? Commands 5-3                    Command line 3-6
? DIRECTORY 5-9                       Editing 3-7
? LIST 5-9                    Constants 2-13
? MEMORY 5-10                    CONTAINS 2-11
? QUERY 5-10
? STATUS 5-11                    D
? STATUS FILE 5-11                DATA 5-33, 5-116
? TEXT 5-12                    Date 2-6
@ 5-4                        Date format 2-6
                        DATE$ 5-34
A                        DATEBASE 5-35
ABS 5-13                    DAY 5-36
ADD 5-14                    DAY$ 5-37
AFTER GROUP 5-17                DAYS 5-38
AFTER REPORT 5-18                DELETE 5-39
APPEND 5-83, 5-103                DESCENDING 5-106
Arithmetic operators 2-7            DIRECTORY 5-40
Arrays 2-4                      See ? DIRECTORY
ASC 5-18                    DISKSPACE 5-41
ASCENDING 5-106                    DOWN 5-4
ASK 5-19
ATN 5-20                    E
ATTR 5-4                    EDIT 5-42
                        Editing keys
B                          Command line 3-7
Batch mode 5-148                  Program 3-5
BEFORE GROUP 5-21                EJECT 5-43
BELL 5-22                    END 5-44
BF 5-4                        END GROUP 5-44
BG 5-4                        END HEADING 5-45
BLANK 5-22                    END REPORT 5-45
BREAK ON/OFF 5-23                EOF 5-48
                        ERASE 5-49

  PAGING 5-144                    TO FILE 5-141
  RECORD 5-145                    TO PRT 5-141
  TABLE 5-145                    TODAY 5-153
  View mode 5-145                TRIM$ 5-154
SGN 5-145
SHOW 5-146                    U
SIN 5-147                    UCASE$ 5-154
Sorting data 5-106                UL 5-4
SPACE$ 5-147                    Update 5-155
SQR 5-148                      Load 5-83
Start up program 3-9                  Save 5-130
STATUS
  See ? STATUS                    V
STORE 5-148                    VAL 5-156
STR$ 5-150                    Variables 2-2
String variables 2-4                  Arrays 2-4
Syntax 2-15                      Names 2-2
System status 5-11                  Numeric 2-3
System variables 2-4                  String 2-4
                          System 2-4
T                        VIEW 5-157
TAN 5-151
Ternary operator 5-81                W
Text                        WAIT 5-157
  Load 5-83                    WEND 5-160
  Outputting files 5-12                WHERE 5-158
  Save 5-130                    WHILE 5-160
THOUSECS 5-151
Time 2-6                    Y
TIME$ 5-152                    YEAR 5-160
TIMEVAL 5-152

============================================================================
     DOCS PROVIDED BY RAP AND -+*+-THE SOUTHERN STAR-+*+- for M.A.A.D.
============================================================================